Copyright © 1997 - 2023 por el PHP Documentation Group. Este material puede ser distribuido solamente sujeto a los términos y condiciones establecidos por la licencia de Creative Commons Attribution 3.0 o superior. Una copia de laLicencia de Commons Attribution 3.0está distribuida con este manual. La versión más reciente está disponible en» http://creativecommons.org/licenses/by/3.0/.
Si está interesado en la redistribución o republicación de este documento completa o parcialmente, con o sin modificaciones, y si tiene alguna pregunta, por favor contacte con los propietarios del Copyright en» doc-license@lists.php.net. Observe que esta dirección está ligada a una lista de correo pública.
PHP, acrónimo de "PHP: Hypertext Preprocessor", es un lenguaje de 'scripting' de propósito general y de código abierto que está especialmente pensado para el desarrollo web y que puede ser embebido en páginas HTML. Su sintaxis recurre a C, Java y Perl, siendo así sencillo de aprender. El objetivo principal de este lenguaje es permitir a los desarrolladores web escribir dinámica y rápidamente páginas web generadas; aunque se puede hacer mucho más con PHP.
Este manual consiste principalmente en unareferencia de funciones, aunque también contiene unareferencia del lenguaje, explicaciones de algunas de lascaracterísticasimportantes de PHP, y otra informaciónsuplementaria.
Este manual se puede descargar en diferentes formatos en» https://www.php.net/download-docs.php. Puede encontrarse más información sobre cómo se desarrolla este manual en el apéndice"Acerca de este manual". Si está interesado en laHistoria de PHP, visite el apéndice correspondiente.
Destacamos a las personas actualmente más activas al frente del manual, pero hay muchos más contribuyentes que nos ayudan en nuestro trabajo o han brindado una gran cantidad de ayuda al proyecto en el pasado. Hay muchísima gente anónima que ayudó con notas de usuario en las páginas del manual, que continuamente son incluidas en las referencias, labor de la que también estamos muy agradecidos. Todas las listas siguientes están en orden alfabético.
Los siguientes contribuyentes deberían ser reconocidos por el impacto de lo que han hecho y/o continúan haciendo añadiendo contenido al manual: Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar y Andrei Zmievski.
Los siguientes contribuyentes han hecho un importante trabajo editando el manual: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson y Egon Schmid.
Los mantenedores actualmente más activos son: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda y Maciek Sokolewicz.
Estas personas también pusieron mucho esfuerzo en la administración de las notas de usuario: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles y Jeroen van Wolffelaar.
PHP(acrónimo recursivo dePHP: Hypertext Preprocessor) es un lenguaje de código abierto muy popular especialmente adecuado para el desarrollo web y que puede ser incrustado en HTML.
Bien, pero ¿qué significa realmente? Un ejemplo nos aclarará las cosas:
Ejemplo #1 Un ejemplo introductorio
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo</title>
</head>
<body>
<?php
echo"¡Hola, soy un script de PHP!";
?>
</body>
</html>En lugar de usar muchos comandos para mostrar HTML (como en C o en Perl), las páginas de PHP contienen HTML con código incrustado que hace "algo" (en este caso, mostrar "¡Hola, soy un script de PHP!). El código de PHP está encerrado entre lasetiquetas especiales de comienzo y final<?phpy?>que permiten entrar y salir del "modo PHP".
Lo que distingue a PHP de algo del lado del cliente como Javascript es que el código es ejecutado en el servidor, generando HTML y enviándolo al cliente. El cliente recibirá el resultado de ejecutar el script, aunque no se sabrá el código subyacente que era. El servidor web puede ser configurado incluso para que procese todos los ficheros HTML con PHP, por lo que no hay manera de que los usuarios puedan saber qué se tiene debajo de la manga.
Lo mejor de utilizar PHP es su extrema simplicidad para el principiante, pero a su vez ofrece muchas características avanzadas para los programadores profesionales. No sienta miedo de leer la larga lista de características de PHP. En unas pocas horas podrá empezar a escribir sus primeros scripts.
Aunque el desarrollo de PHP está centrado en la programación de scripts del lado del servidor, se puede utilizar para muchas otras cosas. Siga leyendo y descubra más en la sección¿Qué puede hacer PHP?, o vaya directo altutorial introductoriosi solamente está interesado en programación web.
Cualquier cosa. PHP está enfocado principalmente a la programación de scripts del lado del servidor, por lo que se puede hacer cualquier cosa que pueda hacer otro programa CGI, como recopilar datos de formularios, generar páginas con contenidos dinámicos, o enviar y recibir cookies. Aunque PHP puede hacer mucho más.
Existen principalmente tres campos principales donde se usan scripts de PHP.
PHP puedeemplearseen todos los sistemas operativos principales, incluyendo Linux, muchas variantes de Unix (incluyendo HP-UX, Solaris y OpenBSD), Microsoft Windows, macOS, RISC OS y probablemente otros más. PHP admite la mayoría de servidores web de hoy en día, incluyendo Apache, IIS, y muchos otros. Esto incluye cualquier servidor web que pueda utilizar el binario de PHP FastCGI, como lighttpd y nginx. PHP funciona tanto como módulo como procesador de CGI.
De modo que con PHP, se tiene la libertad de elegir el sistema operativo y el servidor web. Además, se tiene la posibilidad de utilizar programación por procedimientos o programación orientada a objetos (POO), o una mezcla de ambas.
Con PHP no se está limitado a generar HTML. Entre las capacidades de PHP se incluyen la creación de imágenes, ficheros PDF e incluso películas Flash (usando libswf y Ming) generadas sobre la marcha. También se puede generar fácilmente cualquier tipo de texto, como XHTML y cualquier otro tipo de fichero XML. PHP puede autogenerar estos ficheros y guardarlos en el sistema de ficheros en vez de imprimirlos en pantalla, creando una caché en el lado del servidor para contenido dinámico.
Una de las características más potentes y destacables de PHP es su soporte para unamplio abanico de bases de datos. Escribir una página web con acceso a una base de datos es increíblemente simple utilizando una de las extensiones específicas de bases de datos (p.ej., paramysql), o utilizar una capa de abstracción comoPDO, o conectarse a cualquier base de datos que admita el estándar de Conexión Abierta a Bases de Datos por medio de la extensiónODBC. Otras bases de datos podrían utilizarcURLosockets, como lo hace CouchDB.
PHP también cuenta con soporte para comunicarse con otros servicios usando protocolos tales como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (en Windows) y muchos otros. También se pueden crear sockets de red puros e interactuar usando cualquier otro protocolo. PHP tiene soporte para el intercambio de datos complejos de WDDX entre virtualmente todos los lenguajes de programación web. Y hablando de interconexión, PHP tiene soporte para la instalación de objetos de Java y emplearlos de forma transparente como objetos de PHP.
PHP tiene útiles características deprocesamiento de texto, las cuales incluyen las expresiones regulares compatibles con Perl (PCRE), y muchas extensiones y herramientas para elacceso y análisis de documentos XML. PHP estandariza todas las extensiones XML sobre el fundamento sólido delibxml2, y amplía este conjunto de características añadiendo soporte paraSimpleXML,XMLReaderyXMLWriter.
Existen otras extensiones interesantes, las cuales están categorizadasalfabéticamentey porcategoría. También hay extensiones adicionales de PECL que podrían estar documentadas o no dentro del manual de PHP, tal como» XDebug.
Como se puede apreciar, esta página no es suficiente para enumerar todas las características y beneficios que ofrece PHP. Consulte las seccionesInstalación de PHPyReferencia de las funcionespara una explicación de las extensiones mencionadas aquí.
A continuación, nos gustaría mostrarle lo esencial de PHP en un corto y sencillo tutorial. Este documento solamente trata de la creación de páginas web dinámicas con PHP, aunque PHP no solamente es capaz de crear páginas web. Consulte la sección titulada¿Qué puede hacer PHP?para más información.
Las páginas web que usan PHP se tratan igual que páginas HTML comunes y corrientes, y se pueden crear y editar de la misma manera que normalmente se crean páginas HTML.
En este manual se asume que se cuenta con un servidor que tiene soporte activado para PHP y que todos los ficheros con la extensión.phpson tratados por PHP. En la mayoría de servidores, esta es la extensión predeterminada para los ficheros de PHP, aunque puede preguntar al administrador de su servidor para estar seguro. Si el servidor tiene soporte para PHP, entonces no es necesario hacer nada. Simplemente cree sus ficheros.php, guárdelos en su directorio web y el servidor los analizará por usted. No hay necesidad de compilar nada o instalar otras herramientas. Piense en estos ficheros habilitados para PHP como simples ficheros HTML con el añadido de una nueva familia de etiquetas mágicas que permiten todo tipo de cosas.
Digamos que quiere ahorrar el preciado ancho de banda y trabajar localmente. En este caso, querrá instalar un servidor web, como» Apache, y por supuesto» PHP. Lo más seguro es que también quiera instalar una base de datos como» MySQL.
Puede instalarlos de forma independiente o bien puede elegir una manera más sencilla. Este manual contieneInstrucciones de instalación de PHP(asumiendo que tiene algún tipo de servidor web ya configurado). Si tuviera problemas con la instalación, sugerimos que formule sus preguntas en nuestra» lista de correo de instalación. Si elige la manera más sencilla,» localice un paquete preconfiguradopara su sistema operativo, el cual instala automáticamente todo esto con únicamente unos pocos clics de ratón. Es sencillo configurar un servidor web con soporte para PHP en cualquier sistema operativo, incluyendo MacOSX, Linux y Windows. En Linux, podría encontrar útil» rpmfindy» PBonepara localizar los RPM. También puede visitar» apt-getpara buscar paquetes para Debian..
Comience por crear un fichero llamadohola.phpy póngalo en el directorio raíz de su servidor web (DOCUMENT_ROOT) con el siguiente contenido:
Ejemplo #1 Nuestro primer script de PHP:hola.php
<html>
<head>
<title>Prueba de PHP</title>
</head>
<body>
<?phpecho'<p>Hola Mundo</p>';?>
</body>
</html>Utilice su navegador web para acceder al fichero con el URL de su servidor, finalizado con la referencia al fichero/hola.php. Si está programando localmente, este URL será algo parecido ahttp://localhost/hola.phpohttp://127.0.0.1/hola.php, pero esto depende de la configuración de su servidor web. Si todo está configurado correctamente, el fichero será analizado por PHP y se enviará el siguiente contenido a su navegador:
<html> <head> <title>Prueba de PHP</title> </head> <body> <p>Hola mundo</p> </body> </html>
Este programa es extremadamente simple y realmente no es necesario utilizar PHP para crear una página como esta. Lo único que muestra es:Hola mundoempleando la sentenciaechode PHP. Observe que el ficherono necesita ser ejecutableo especial de ninguna forma. El servidor reconoce que este fichero necesita ser interpretado por PHP debido al empleo de la extensión ".php", ya que el servidor está configurado para enviarlo a PHP. Piense como si fuera un fichero HTML normal que tiene una serie de etiquetas especiales disponibles con las que puede hacer muchas cosas interesantes.
Si intentó usar este ejemplo y no produjo ningún resultado, se le preguntó si deseaba descargar el fichero, o se mostró todo el fichero como texto, lo más seguro es que PHP no se encuentre habilitado en su servidor o no esté configurado adecuadamente. Pídale a su administrador que lo habilite utilizando el capítuloInstalacióndel manual. Si está trabajando localmente, lea también el capítulo dedicado a la instalación para asegurarse de que todo esté configurado adecuadamente. Asegúrese de que está accediendo al fichero mediante http y que el servidor muestre el resultado. Si está abriendo el fichero desde el sistema de ficheros, probablemente no será analizado por PHP. Si el problema persiste, no dude en usar alguna de las múltiples opciones del» Soporte para PHP.
El objetivo de este ejemplo es el formato de las etiquetas especiales de PHP. En este ejemplo utilizamos<?phppara indicar el inicio de una etiqueta de PHP. Después ponemos la sentencia y abandonamos el modo PHP añadiendo la etiqueta de cierre?>. De esta manera, se puede entrar y salir del modo PHP en un fichero HTML cada vez que se quiera. Para más información, lea la sección del manual tituladaSintaxis básica de PHP.
Nota:Una observación sobre los avances de línea
Los avances de línea tienen poco sentido en HTML, aunque sigue siendo buena idea hacer que el código HTML se vea limpio y claro poniendo avances de línea. PHP automáticamente eliminará los avances de línea que estén después de una etiqueta de cierre
?>. Esto puede ser muy útil al poner muchos bloques de PHP o incluir ficheros que contienen PHP y que se supone que no deben mostrar nada. Al mismo tiempo, puede resultar un poco confuso. Se puede poner un espacio después de la etiqueta de cierre?>para mostrar forzosamente un espacio y un avance de línea, o se puede poner un avance de línea explícito en el último echo/print dentro del bloque de PHP.
Nota:Una observación sobre los editores de texto
Hay muchos editores de texto y Entornos de Desarrollo Integrados (IDE por sus siglas en Inglés) que se pueden emplear para crear, editar, y gestionar ficheros de PHP. Se puede encontrar una lista parcial de estos en» Lista de editores de PHP. Si desea recomendar un editor, por favor visite la página mencionada anteriormente y pregunte al mantenedor de la página para que lo incluya en la lista. Contar con un editor que resalte la sintaxis puede ser de mucha ayuda.
Nota:Una observación sobre los procesadores de texto
Los procesadores de texto como StarOffice Writer, Microsoft Word y Abiword no son buenas opciones para editar ficheros de PHP. Si desea utilizar uno de estos programas para probar este script, asegúrese de guardar el documento comotexto sin formato, o de lo contrario, PHP no será capaz de leerlo y ejecutarlo.
Nota:Una observación sobre el Bloc de Notas de Windows
Si escribe sus scripts de PHP usando el Bloc de Notas de Windows, debe asegurarse de que sus ficheros sean guardados con la extensión.php. (El Bloc de Notas automáticamente añade la extensión.txta los ficheros a menos que siga los siguientes pasos para prevenirlo). Cuando guarde el fichero y el programa le pregunte qué nombre desea dar al fichero, entrecomille el nombre (es decir, "hola.php"). Una alternativa es hacer clic en el menú desplegable "Documentos de Texto (*.txt)" del cuadro de diálogo "Guardar como", y cambiar a la opción "Todos los archivos (*.*)". Aquí puede escribir el nombre del fichero sin las comillas.
Ahora que ha creado un pequeño script de PHP que funciona correctamente, es hora de crear el script de PHP más famoso: hacer una llamada a la funciónphpinfo()para obtener mucha información útil acerca de su sistema y configuración, como lasvariables predefinidasdisponibles, los módulos de PHP cargados, y los ajustes deconfiguración. Tómese algo de tiempo para revisar esta importante información.
Ejemplo #2 Obtener la información del sistema desde PHP
<?php phpinfo();?>Hagamos ahora algo que puede ser más útil. Vamos a comprobar qué tipo de navegador está utilizando el usuario visitante. Para hacerlo, vamos a comprobar el string del agente de usuario que el navegador envía como parte de la petición HTTP. Esta información es almacenada en unavariable. En PHP, las variables siempre comienzan con un signo de dólar. La variable que nos interesa ahora es$_SERVER['HTTP_USER_AGENT'].
Nota:
$_SERVERes una variable especial reservada por PHP que contiene toda la información del servidor web. Es conocida como una superglobal. Consulte la página del manual sobreSuperglobalespara más información.
Para mostrar esta variable, se puede hacer simplemente:
Ejemplo #1 Imprimir una variable (elemento de array)
<?php
echo$_SERVER['HTTP_USER_AGENT'];
?>Un ejemplo del resultado de este script podría ser:
Hay muchostiposde variables en PHP. En el ejemplo anterior se muestra un elemento de unArray. Los arrays pueden ser muy útiles.
$_SERVERes simplemente una variable que se encuentra disponible automáticamente en PHP. Se puede encontrar una lista en la secciónVariables reservadasdel manual, o se puede obtener una lista completa observando la salida de la funciónphpinfo()usada en el ejemplo de la sección anterior.
Puede usar múltiples sentencias de PHP dentro de una etiqueta de PHP y crear pequeños bloques de código que realicen más que un simple 'echo'. Por ejemplo, si se quisiera detectar el uso de Internet Explorer, se podría hacer algo así:
Ejemplo #2 Ejemplo usandoestructuras de controlyfunciones
<?php
if (strpos($_SERVER['HTTP_USER_AGENT'],'MSIE') !==FALSE) {
echo'Está usando Internet Explorer.<br />';
}
?>Un ejemplo del resultado de este script sería:
Está usando Internet Explorer.<br />
Aquí hemos introducido un par de conceptos nuevos. Tenemos una sentenciaif. Si está familiarizado con la sintaxis básica del lenguaje C, debería parecerle lógico. De lo contrario, probablemente debería conseguir un libro que le introduzca a PHP, y leer el primer par de capítulos, o leer la parte del manual tituladaReferencia del lenguaje.
El segundo concepto que introducimos fue la función llamada astrpos().strpos()es una función integrada en PHP que busca un string dentro de otro. En este caso estamos buscando'MSIE'(también llamado aguja) dentro de$_SERVER['HTTP_USER_AGENT'](también llamado pajar). Si el string se encuentra dentro del pajar, la función devuelve la posición de la aguja relativa al inicio del pajar. De lo contrario, devuelvefalse. Si no devuelvefalse, la expresiónifse evalúa comotruey se ejecuta el código entre llaves {}. De lo contrario, el código no será ejecutado. Tómese la libertad de crear ejemplos similares, conif,else, y otras funciones comostrtoupper()ystrlen(). Cada página del manual relacionada también contiene ejemplos. Si no está seguro de cómo usar estas funciones, es recomendable que lea las páginas del manual sobreCómo interpretar una definición de funcióny la sección sobreFunciones de PHP.
Podemos dar un paso más y mostrar cómo se puede entrar y salir del modo PHP incluso en medio de un bloque de código de PHP:
Ejemplo #3 Mezcla de los modos HTML y PHP
<?php
if (strpos($_SERVER['HTTP_USER_AGENT'],'MSIE') !==FALSE) {
?>
<h3>strpos() debe haber devuelto no falso</h3>
<p>Está usando Internet Explorer</p>
<?php
} else {
?>
<h3>strpos() debe haber devuelto falso</h3>
<p>No está usando Internet Explorer</p>
<?php
}
?>Un ejemplo del resultado del script podría ser:
<h3>strpos() debe haber devuelto no falso</h3> <p>Está usando Internet Explorer</p>
En vez de usar una sentencia echo de PHP para mostrar algo, salimos del modo PHP y enviamos solamente HTML. Este es un punto muy importante y potente que se ha de observar aquí, y es que la fluidez lógica del script permanece intacta. Solamente uno de los bloques HTML terminará siendo enviado al navegador dependiendo del resultado destrpos(). En otras palabras, depende de si el stringMSIEfue encontrada o no.
Otra de las características más potentes de PHP es la forma de gestionar formularios HTML. El concepto básico que es importante entender es que cualquier elemento de un formulario estará disponible automáticamente en sus scripts de PHP. Por favor, lea la sección del manual sobreVariables desde fuentes externaspara obtener más información y ejemplos sobre cómo usar formularios con PHP. Observemos un ejemplo:
Ejemplo #1 Un formulario HTML sencillo
<form action="accion.php" method="post"> <p>Su nombre: <input type="text" name="nombre" /></p> <p>Su edad: <input type="text" name="edad" /></p> <p><input type="submit" /></p> </form>
No hay nada especial en este formulario. Es solamente un formulario HTML sin ninguna clase de etiqueta especial. Cuando el usuario rellena este formulario y oprime el botón de envío, se llama a la páginaaccion.php. En este fichero se podría escribir algo así:
Ejemplo #2 Mostrar información de nuestro formulario
Hola<?phpechohtmlspecialchars($_POST['nombre']);?>.
Usted tiene<?phpecho (int)$_POST['edad'];?>años.Un ejemplo del resultado de este script podría ser:
Hola José. Usted tiene 22 años.
Excepto las partes dehtmlspecialchars()y de(int), debería ser obvio qué es lo que hace el código.htmlspecialchars()garantiza que cualquier carácter que sea especial en html se codifique adecuadamente, de manera que nadie pueda inyectar etiquetas HTML o Javascript en la página. El campo edad, ya que sabemos que es un número, podemosconvertirloa un valor de tipointegerque automáticamente se deshará de cualquier carácter no numérico. También se puede hacer lo mismo con PHP con la extensiónfilter. Las variables$_POST['nombre']y$_POST['edad']son establecidas automáticamente por PHP. Anteriormente hemos usado la superglobal$_SERVER; arriba introdujimos la superglobal$_POST, la cual contiene todos los datos de POST. Observe que elmétodode nuestro formulario es POST. Si hubiésemos usado el métodoGET, nuestra información estaría en su lugar en la superglobal$_GET. También se podría usar la superglobal$_REQUEST, si no le preocupa la fuente de los datos solicitados. Contiene toda la información de los datos de GET, POST y COOKIE mezclada.
En PHP, también puede tratar con entradas de XForms; aunque probablemente al principio se sienta cómodo con los formularios de HTML, los cuales están ampliamente respaldados. A pesar de que trabajar con XForms no es para principiantes, podrían interesarle. Si es así, en la sección de características hay unapequeña introducción a la manipulación de datos recibidos desde XForms.
Con sus nuevos conocimientos debería ser capaz de entender la mayoría del manual y los diversos scripts de ejemplo disponibles en los archivos de ejemplos.
Para ver varias presentaciones que muestran más acerca de lo que puede hacer PHP, véase el Sitio de Material de Conferencias de PHP:» http://talks.php.net/
Antes de empezar con la instalación, primero necesita saber para qué quiere utilizar PHP. Existen tres campos principales donde se puede utilizar PHP tal y como se describe en la sección:¿Qué se puede hacer con PHP?
Para la primera forma mencionada, que es la más común, se necesitan tres cosas: PHP, un servidor web y un navegador web. Seguramente ya disponga del navegador web y, dependiendo de la configuración del sistema operativo, quizá ya tenga un servidor web (p.ej. Apache en Linux y macOS; IIS en Windows). También puede alquilar espacio web en una empresa. De esta forma, no se necesita instalar nada, solo tiene que escribir los scripts de PHP, subirlos al servidor que alquile y ver los resultados en su navegador.
En caso de configurar el servidor y PHP por su cuenta, existen dos opciones para el modo de conectar PHP con el servidor. Para muchos servidores, PHP tiene un módulo de interfaz directo (también llamado SAPI). Entre estos servidores se incluyen Apache, Microsoft Internet Information Server, Netscape y iPlanet. Muchos otros servidores tienen soporte para ISAPI, el módulo de interfaz de Microsoft (OmniHTTPd por ejemplo). Si PHP no tiene soporte para el módulo de su servidor web, siempre puede usarlo como procesador CGI o FastCGI. Esto significa configurar el servidor para usar el CGI ejecutable de PHP para procesar cada una de las peticiones a ficheros PHP en el servidor.
Si también está interesado en usar PHP bajo la línea de comandos (p.ej. escribir scripts que autogeneran imágenes de forma offline, o procesar ficheros de texto dependiendo de los argumentos que se les pasen), siempre necesitará el ejecutable de línea de comandos. Para más información, lea la sección sobreescribir aplicaciones PHP desde la línea de comandos. En este caso, no se necesita ningún servidor o navegador.
Con PHP también se pueden escribir aplicaciones GUI de escritorio usando la extensión PHP-GTK. Este enfoque no tiene nada que ver con escribir páginas web, ya que no se muestra nada de HTML, pero gestiona ventanas y objetos dentro de ellas. Para más información acerca de PHP-GTK, por favor» visite el sitio dedicado a esta extensión. PHP-GTK no está incluido en la distribución oficial de PHP.
De aquí en adelante, esta sección trata de la configuración de PHP para servidores web sobre Unix y Windows con interfaces de módulo de servidor y ejecutables CGI. También se puede encontrar información sobre ejecutables de línea de comandos en las siguientes secciones.
El código fuente de PHP y las distribuciones binarias para Windows pueden encontrarse en» https://www.php.net/downloads.php. Recomendamos elegir un» sitio alternativocercano para descargar las distribuciones.
Esta sección le guiará a través de la configuración general e instalación de PHP sobre sistemas Unix. Asegúrese de investigar cualquier sección específica a su plataforma o servidor web antes de comenzar el proceso.
Tal como el manual lo esboza en la secciónConsideraciones generales de instalación, se está tratando principalmente con configuraciones de PHP centradas en web en esta sección, aunque también se cubrirá el preparar PHP para usarse en línea de comando.
Existen varias maneras de instalar PHP para la plataforma Unix, ya sea con un proceso de compilar y configurar, o a través de varios métodos pre-empaquetados. Esta documentación está enfocada principalmente alrededor del proceso de compilar y configurar PHP. Muchos sistemas estilo Unix tienen algún tipo de sistema de instalación de paquetes. Esto puede ayudar en preparar una configuración standard, pero si se requiere tener un conjunto diferente de características (tales como un servidor seguro, o un manejador diferente de base de datos), podría ser necesario construir PHP y/o el servidor web. Si no se está familiarizado con la construcción y el compilado de su propio software, vale la pena revisar para ver si alguien ya ha construido una versión empaquetada de PHP con las características que se necesitan.
Conocimientos y software necesarios para compilar:
Cuando compile directamente de una fuente Git o después de realizar modificaciones usted necesita también:
El proceso inicial de preparación y configuración de PHP es controlado por el uso de las opciones de línea de comando del scriptconfigure. Es posible obtener una lista de todas las opciones disponibles junto con una descripción corta ejecutando./configure --help. El manual documenta las diferentes opciones por separado. Se encontrarán lasopciones principales en el apéndice, mientras que las diferentes opciones específicas de las extensiones se describen en las páginas de referencia.
Cuando PHP está configurado, se está listo para compilar el módulo y/o ejecutables. El comandomakedebería hacerse cargo de esto. Si falla y no se puede encontrar el porque, véase lasección de problemas.
Nota:
Algunos sistemas UNIX (como OpenBSD y SELinux) pueden deshabilitar el mapeo de páginas tanto en escritura como lectura por razones de seguridad, Lo que se llama PaX MPROTECT o W^X protección contra violaciones. Este tipo de mapeado de memoria es, sin embargo, necesario para el soporte JIT PCRE, por lo que bien PHP debe ser compiladosin soporte PCRE's JIT, o el binario ha de ser cargado en lista blanca por cualquier medio proporcionado por el sistema.
Nota:La compilación cruzada para ARM con el toolchain de herramientas de Android no es compatible actualmente.
Esta sección contiene notas y consejos específicos a las instalaciones de Apache 2.x de PHP sobre sistemas Unix.
No se recomienda utilizar un MPM threaded en producción con Apache 2. Use MPM prefork, que es el MPM por defecto en Apache 2.0 y 2.2. Para información sobre cómo, lea la correspondiente entrada de la FAQ sobre utilizarApache2 con un MPM threaded
La» Documentación de Apachees la fuente de información más autorizada acerca del servidor Apache 2.x. Ahí se puede encontrar más información acerca de las opciones de instalación.
La versión más reciente de Apache HTTP Server puede obtenerse del» Sitio de descargas de Apache, y una versión apropiada de PHP de los lugares anteriormente mencionados. Esta guía rápida solamente cubre lo básico para comenzar con Apache 2.x y PHP. Para obtener más información lea la» Documentación de Apache. Los números de versión han sido omitidos aquí, para asegurar que las instrucciones no sean incorrectas. En los ejemplos siguientes, 'NN' deberá ser reemplazado con la versión específica de Apache que se está utilizando.
Existen actualmente dos versiones de Apache 2.x - está la 2.0 y la 2.2. Mientras que existen varias razones para elegir cada una, la 2.2 es actualmente la versión más reciente, y la que se recomienda, si es que esa opción está disponible. Sin embargo, las instrucciones aquí funcionarán ya sea para 2.0 ó 2.2.
Obténgase el servidor HTTP Apache de la ubicación listada con anterioridad, y desempáquese:
gzip -d httpd-2_x_NN.tar.gz tar -xf httpd-2_x_NN.tar
De la misma manera, obtener y desempacar las fuentes de PHP:
gunzip php-NN.tar.gz tar -xf php-NN.tar
Compilar e instalar Apache. Consúltese la documentación de instalación de Apache para mayores detalles sobre la compilación de Apache.
cd httpd-2_x_NN ./configure --enable-so make make install
Ahora se tiene Apache 2.x.NN disponible debajo de /usr/local/apache2, configurado con soporte para módulos cargables y con el MPM (Módulo de multiproceso) prefork estándar. Para probar la instalación úsese el procedimiento para iniciar el servidor Apache, por ej.:
/usr/local/apache2/bin/apachectl start
/usr/local/apache2/bin/apachectl stop
Ahora, configure y compile PHP. Aquí es donde se personaliza PHP con varias opciones, como qué extensiones se han de habilitar. Ejecute ./configure --help para obtener una lista de opciones disponibles. En el ejemplo se realiza un simple configure con soporte para Apache 2 y MySQL.
Si se compila Apache a partir de los fuentes, tal como se describe anteriormente, el siguiente ejemplo coincidirá con la trayectoria para apxs, pero si se ha instalado Apache de alguna otra manera, será necesario ajustar la trayectoria a apxs apropiadamente. Nótese que algunas distribuciones pueden renombrar apxs cómo apxs2.
cd ../php-NN ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql make make install
Si se decide a cambiar las opciones de configuración después de la instalación, se deben volver a ejecutar los pasos configure, make, y make install. Solamente se necesita reiniciar apache para que el nuevo módulo tenga efecto. Una recompilación de Apache no es necesaria.
Nótese que a menos que se indique lo contrario, 'make install' también instalará PEAR, varias herramientas de PHP tales como phpize, instalará la interfaz de línea de comando (CLI) de PHP, y más.
Configurar php.ini
cp php.ini-development /usr/local/lib/php.ini
Se puede editar el fichero .ini para fijar las opciones de PHP. Si se prefiere tener php.ini en otra ubicación, utilice --with-config-file-path=/alguna/trayectoria en el paso 5.
Si en vez de eso se elige php.ini-production, asegúrese de leer la lista de cambios al interior, ya que afectan como se comporta PHP.
Edítese httpd.conf para cargar el módulo PHP. La trayectoria a la derecha de la sentencia LoadModule debe apuntar a la trayectoria del módulo PHP en el sistema. El make install anterior podría ya haber agregado esto automáticamente, pero asegúrese de revisar.
Para PHP 7:
LoadModule php7_module modules/libphp7.so
Para PHP 5:
LoadModule php5_module modules/libphp5.so
Indicar a Apache que procese ciertas extensiones como PHP. Por ejemplo, hágase que Apache procese ficheros .php como PHP. En vez de solamente utilizar la directiva de Apache AddType, se desea evitar subidas de ficheros potencialmente peligrosas y que ficheros creados tal como exploit.php.jpg sean ejecutados como PHP. Utilizando este ejemplo, se puede hacer que cualquier extensión o extensiones sean procesadas como PHP simplemente añadiéndolas. Se agregará .php para demostrarlo.
<FilesMatch \.php$>
SetHandler application/x-httpd-php
</FilesMatch>O, si se deseara permitir que ficheros .php, .php2, .php3, .php4, .php5, .php6, y .phtml fuesen ejecutados como PHP, pero nada más, se utilizaría esto:
<FilesMatch "\.ph(p[2-1]?|tml)$">
SetHandler application/x-httpd-php
</FilesMatch>Y para permitir que ficheros .phps sean manejados por el filtro de fuentes de php, y desplegado como código fuente con sintaxis resaltada, se utiliza esto:
<FilesMatch "\.phps$">
SetHandler application/x-httpd-php-source
</FilesMatch>mod_rewrite puede ser utilizado para permitir que cualquier fichero .php arbitrario sea desplegado como código fuente con sintaxis resaltada, sin tener que renombrarlo o copiarlo a un fichero .phps:
RewriteEngine On RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]
El filtro de código fuente php no debe habilitarse en sistemas de producción, donde podría exponer información confidencial o de alguna otra manera sensible incluida en código fuente.
Utilícese el procedimiento normal para iniciar el servidor Apache, por ej.:
/usr/local/apache2/bin/apachectl start
O
service httpd restart
Siguiendo los pasos anteriores se tendrá corriendo un servidor web Apache2 con soporte para PHP como un móduloSAPI. Por supuesto existen muchas opciones más de configuración disponibles para Apache y PHP. Para más información teclee./configure --helpen el árbol de fuentes correspondiente.
Apache se puede compilar con soporte multihilos seleccionando elworkerMPM, en vez delpreforkMPM standard, cuando Apache se compila. Esto se realiza agregando la siguiente opción al argumento pasado a ./configure, en el paso 3 anterior:
--with-mpm=worker
Esto no debe llevarse a cabo sin ser consciente de las consecuencias de esta decisión, y tener al menos un ligero entendimiento acerca de las implicaciones. La documentación de Apache al respecto de» MPM-Modulesdiscute los MPM en forma mucho más detallada.
Nota:
LasPreguntas frecuentes de Apache MultiViewsdiscute acerca del uso de multiviews con PHP.
Nota:
Para compilar una versión multihilo de Apache, el sistema destino debe soportar hilos. En este caso, PHP también debe compilarse con la opción Zend Thread Safety (ZTS) experimental. Bajo esta configuración, no todas las extensiones se encontrarán disponibles. La configuración recomendada es compilar Apache con el MPM-modulepreforkpor omisión.
Esta documentación cubre la instalación y configuración de PHP con PHP-FPM para un servidor HTTP de Nginx 1.4.x.
En esta guía se asume que se ha construido Nginx desde el código fuente, por lo que todos los ficheros binarios y de configuración están ubicados en/usr/local/nginx. Si este no es el caso y se ha obtenido Nginx a través de otros medios, consúltese la» Wiki de Nginxpara traducir este manual a una configuración propia.
Esta guía cubre la configuración básica de un servidor Nginx para procesar aplicaciones de PHP y servirlas en el puerto 80. Se recomienda estudiar la documentación de Nginx y de PHP-FPM para poder optimizar la configuración más allá del ámbito de esta documentación.
Obsérvese que en esta documentación se han reemplazado los números de versión con una 'x' para asegurarse de que sea correcta en el futuro; se han de reemplazar estos con los números de versión correspondiente cuando sea necesario.
Se recomienda visitar la página de» instalaciónde la Wiki de Nginx para obtener e instalar Nginx en un sistema propio.
Obtener y desempaquetar el código fuente de PHP:
tar zxf php-x.x.x
Configurar y construir PHP. Aquí es donde se personaliza PHP con varias opciones, como qué extensiones se habilitarán. Ejecutar ./configure --help para enumerar las opciones disponibles. En este ejemplo se realiza una configuración sencilla con soporte para PHP-FPM y MySQL.
cd ../php-x.x.x ./configure --enable-fpm --with-mysql make sudo make install
Obtener y mover los ficheros de configuración a sus ubicaciones correctas
cp php.ini-development /usr/local/php/php.ini cp /usr/local/etc/php-fpm.conf.default /usr/local/etc/php-fpm.conf cp sapi/fpm/php-fpm /usr/local/bin
Es importante prevenir que Nginx pase peticiones al «backend» de PHP-FPM si el fichero no existe, evitando así la inyección arbitraria de scripts.
Esto se puede corregir estableciendo la directivacgi.fix_pathinfoa0dentro del fichero php.ini.
Cargar el php.ini:
vim /usr/local/php/php.ini
Localizarcgi.fix_pathinfo=y modificarla como sigue:
cgi.fix_pathinfo=0
Se debe modificar php-fpm.conf para especificar que php-fpm debe ejecutarse como el usuario www-data y el grupo www-data antes de poder iniciar el servicio:
vim /usr/local/etc/php-fpm.conf
Buscar y modificar lo siguiente:
; Usuario/grupo de procesos de Unix ; Nota: El usuario es obligatorio. Si el grupo no se establece, se utilizará ; el grupo predeterminado del usuario. user = www-data group = www-data
Ahora se puede iniciar el servicio de php-fpm:
/usr/local/bin/php-fpm
Esta guía no continua configurando php-fpm; si se tiene interés en una configuración mayor de php-fpm, consulte la documentación.
Ahora Nginx debe configurarse para que pueda procesar aplicaciones de PHP:
vim /usr/local/nginx/conf/nginx.conf
Modificar el bloque de ubicaciones predeterminado para que intente servir ficheros .php:
location / {
root html;
index index.php index.html index.htm;
}El siguiente paso es asegurarse de que los ficheros .php se pasan al «backend» de PHP-FPM. Bajo el bloque de ubicaciones predeterminado de PHP comentado, añadir lo siguiente:
location ~* \.php$ {
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
}Reiniciar Nginx.
sudo /usr/local/nginx/sbin/nginx -s stop sudo /usr/local/nginx/sbin/nginx
Crear un fichero de prueba
rm /usr/local/nginx/html/index.html echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php
Ahora, navegar a http://localhost. phpinfo() debería mostrarse.
Siguiendo los pasos anteriores se tendrá un servidor web Nginx funcionando con soporte para PHP como móduloSAPI. Por supuesto, existen muchas más opciones de configuración disponibles para Nginx y PHP. Para más información, teclear./configure --helpen el árbol de código fuente correspondiente.
Esta sección contiene anotaciones y consejos específicos para la instalación de PHP en Lighttpd 1.4 para sistemas Unix.
Por favor, antes de continuar consulte el» sistema de seguimiento de Lighttpdpara saber cómo instalar Lighttpd apropiadamente.
La SAPI recomendada para conectar PHP a Lighttpd es Fastcig. Esta SAPI viene habilitada por omisión en php-cgi PHP 5.3. En versiones anteriores debe configurarse PHP con --enable-fastcgi. Para verificar que PHP tiene fastcgi habilitado,php -vdebe contenerPHP 5.2.5 (cgi-fcgi)En versiones anteriores a PHP 5.2.3, fastcgi estaba habilitado en el binario de php (no había php-cgi).
Para configurar Lighttpd para que se conecte a php y lance procesos fastcgi, debe editar lighttpd.conf. Se recomienda utilizar sockets para conectar fastcgi a los procesos del sistema local.
Ejemplo #1 Extracto de lighttpd.conf
server.modules += ( "mod_fastcgi" )
fastcgi.server = ( ".php" =>
((
"socket" => "/tmp/php.socket",
"bin-path" => "/usr/local/bin/php-cgi",
"bin-environment" => (
"PHP_FCGI_CHILDREN" => "16",
"PHP_FCGI_MAX_REQUESTS" => "10000"
),
"min-procs" => 1,
"max-procs" => 1,
"idle-timeout" => 20
))
)
La directiva bin-path permite a lighttpd lanzar procesos fastcgi dinámicamente. PHP creará nuevos procesos hijos según se especifique en la variable de entorno PHP_FCGI_CHILDREN. La directiva "bin-environment" establece el entorno de los nuevos procesos. Cada vez que se alcance un determinado número de peticiones, determinado por PHP_FCGI_MAX_REQUEST, se matará un proceso. Las directivas "min-procs" y "max-procs" deben, por norma general, evitarse con PHP. PHP gestiona sus propios hijos, de forma que cachés como APC sólo estarán disponibles para los procesos gestionados por PHP. Si se establece "min-procs" a un número superior a 1, el número total de procesos oyentes en php se multiplicará por PHP_FCGI_CHILDREN (2 min-procs * 16 hijos produce 32 oyentes).
Lighttpd contiene el programa spawn-fcgi que facilita lanzar procesos fastcgi.
Pese a que es más laborioso, es posible lanzar procesos sin spawn-fcgi. La variable de entorno PHP_FCGI_CHILDREN controla cuántos procesos hijo de PHP se lanzarán para manejar las peticiones entrantes. PHP_FCGI_MAX_REQUESTS determinará el tiempo de vida (en peticiones) de cada proceso hijo. Aquí se muestra un script en bash que asiste en la creación de procesos php.
Ejemplo #2 Lanzando oyentes FastCGI
#!/bin/sh
# Ubicación del binario php-cgi
PHP=/usr/local/bin/php-cgi
# Ubicación del fichero PID
PHP_PID=/tmp/php.pid
# Enlazando a una dirección
#FCGI_BIND_ADDRESS=10.0.1.1:10000
# Enlazando a un socket de dominio
FCGI_BIND_ADDRESS=/tmp/php.sock
PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000
env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
$PHP -b $FCGI_BIND_ADDRESS &
echo $! > "$PHP_PID"
Para poder tener aplicaciones escalables, pueden lanzarse instancias de fastcgi en múltiples equipos remotos.
Ejemplo #3 Conexión a instancias de php-fastcgi remotas
fastcgi.server = ( ".php" =>
(( "host" => "10.0.0.2", "port" => 1030 ),
( "host" => "10.0.0.3", "port" => 1030 ))
)
LiteSpeed PHP (LSPHP) es una compilación optimizada de PHP creada para funcionar con los productos de LiteSpeed a través de LiteSpeed SAPI. LSPHP se ejecuta como su propio proceso y tiene su propio binario independiente, el cual puede usarse como un simple binario de línea de comandos para ejecutar scripts PHP desde la terminal.
LSAPI es una API altamente optimizada que permite la comunicación entre LiteSpeed y motores web de terceros. Su protocolo es similar al FCGI, pero más eficiente.
Esta documentación abarcará la instalación y configuración de PHP con LSAPI tanto para un servidor web LiteSpeed como para un servidor web OpenLiteSpeed.
Esta guía asumirá que LSWS u OLS están instalados con sus rutas y banderas predeterminadas. El directorio de instalación predeterminado para ambos servidores será /usr/local/lsws y ambos se podrán ejecutar desde el subdirectorio bin.
Tenga en cuenta que a lo largo de esta documentación, los números de versión han sido reemplazados con unaxpara garantizar que esta se mantenga correcta en el futuro. Por favor, reemplácelos, según sea necesario, con los números de versión correspondientes.
Para obtener e instalar el servidor web LiteSpeed o OpenLiteSpeed, visite la» página de instalaciónde la wiki de LiteSpeed, o la» página de instalaciónde la wiki de OpenLiteSpeed.
Obtenga y descomprima el código fuente de PHP:
mkdir /home/php cd /home/php wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror tar -zxvf php-x.x.x.tar.gz cd php-x.x.x
Configure y compile PHP. Aquí es donde PHP se puede personalizar con varias opciones, como pudieran ser las extensiones que se habilitarán. Ejecute ./configure --help para obtener una lista de opciones. En el ejemplo, utilizaremos las opciones de configuración recomendadas predeterminadas para el servidor web LiteSpeed:
./configure ... '--with-litespeed' make sudo make install
Compruebe la instalación de LSPHP
Una de las formas más simples de verificar si la instalación de PHP fue exitosa es ejecutar el siguiente código:
cd /usr/local/lsws/fcgi-bin/ ./lsphp5 -v
Dicho código debería devolver información sobre la nueva compilación de PHP:
PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19) Copyright (c) 1997-2014 The PHP Group Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies
Observe el textolitespeedentre paréntesis. Esto significa que el binario de PHP ha sido construido con soporte para LSAPI.
Siguiendo los pasos anteriores, el servidor web LiteSpeed / OpenLiteSpeed debería encontrarse ejecutándose con soporte para PHP como extensión SAPI. Hay muchos más opciones de configuración disponibles para LSWS / OLS y PHP. Para más información, eche un vistazo a la wiki de LiteSpeed sobre» PHP.
Usando LSPHP desde la línea de comando:
El modo de línea de comandos LSPHP (LSAPI + PHP) se utiliza para procesar scripts PHP que se ejecutan en un servidor remoto que no necesariamente tiene un servidor web en ejecución. Se utiliza para procesar scripts PHP que residen en un servidor web local (separado). Esta configuración es adecuada para la escalabilidad del servicio, ya que el procesamiento de PHP se descarga a un servidor remoto.
Inicie lsphp desde la línea de comandos en un servidor remoto: LSPHP es un ejecutable y puede iniciarse manualmente y vincularse a IPv4, IPv6 o direcciones de socket de dominio Unix con la opción de línea de comandos -b socket_address
Ejemplos:
Haga que LSPHP utilice el puerto 3000 en todas las direcciones IPv4 e IPv6:
/path/to/lsphp -b [::]:3000
Haga que LSPHP utilice el puerto 3000 en todas las direcciones IPv4:
/path/to/lsphp -b *:3000
Haga que LSPHP utilice la dirección 192.168.0.2:3000:
/path/to/lsphp -b 192.168.0.2:3000
Haga que LSPHP acepte solicitudes en el socket de dominio Unix/tmp/lsphp_manual.sock:
/path/to/lsphp -b /tmp/lsphp_manual.sock
Las variables de entorno se pueden agregar antes del ejecutable LSPHP:
PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port
Actualmente, LiteSpeed PHP se puede usar con el servidor web LiteSpeed, OpenLiteSpeed y Apache mod_lsapi. Para pasos sobre configuración del lado del servidor, visite las páginas wiki de» LiteSpeedy» OpenLiteSpeed.
LSPHP también se puede instalar de otras formas:
CentOS: En CentOS, LSPHP puede ser instalado tanto desde el repositorio de LiteSpeed como desde el de Remi utilizando» RPM.
Debian: En Debian, LSPHP puede ser instalado desde el repositorio de LiteSpeed Repository utilizando» apt.
cPanel: Visite la respectiva» página de la wikisobre cómo instalar LSPHP en cPanel y LSWS/OLS usando EasyApache 4.
Plesk: Plesk puede ser usado con LSPHP en CentOS, CloudLinux, Debian, y Ubuntu. Para más detalles en este tema, visite la correspondiente» página de la wiki
Por defecto, PHP se construye como un programaCLIyCGI, que puede ser utilizado para el procesamiento de CGI. Si está ejecutando un servidor web PHP tiene soporte para los módulos, por lo general debe irse por esta solución por razones de rendimiento. Sin embargo, la versión CGI permite a los usuarios ejecutar diferentes páginas con PHP bajo diferentes identificadores de usuarios.
Al usar el modo CGI, su servidor esta expuesto a diferentes ataques. Por favor, leer la secciónSeguridad con CGIpara aprender cómo defenderse de estos ataques.
Si has construido PHP como un programa CGI, puede probar su construcción escribiendomake test. Siempre es una buena idea probar su construcción. De esta manera usted puede encontrar un problema al principio con PHP en la plataforma, en lugar de tener que luchar con él más adelante.
Algunosservidores suministrando variables de entornono se definen en las actuales» CGI/1.1 specification. Sólo las siguientes variables no se definen:AUTH_TYPE,CONTENT_LENGTH,CONTENT_TYPE,GATEWAY_INTERFACE,PATH_INFO,PATH_TRANSLATED,QUERY_STRING,REMOTE_ADDR,REMOTE_HOST,REMOTE_IDENT,REMOTE_USER,REQUEST_METHOD,SCRIPT_NAME,SERVER_NAME,SERVER_PORT,SERVER_PROTOCOL, andSERVER_SOFTWARE. Todo lo demás debe ser tratado como "extensiones de proveedor".
Esta sección contiene notas y consejos específicos a la instalación de PHP sobre» OpenBSD 3.6.
Utilizar paquetes binarios para instalar PHP sobre OpenBSD es el método más simple y recomendado. El paquete principal ha sido separado de los distintos módulos, y cada uno puede ser instalado removido independientemente de los otros. Los ficheros que se necesitan pueden ser encontrados en el CD de OpenBSD o en el sitio FTP.
El paquete principal que se necesita instalar esphp4-core-4.3.8.tgz, que contiene el motor básico (además de gettext e iconv). Seguido, tómese un vistazo a los paquetes de módulos, tales comophp4-mysql-4.3.8.tgzophp4-imap-4.3.8.tgz. Se necesita emplear el comandophpxspara activar y desactivar estos módulos en el ficherophp.ini.
Ejemplo #1 Ejemplo de instalación de paquete de OpenBSD
# pkg_add php4-core-4.3.8.tgz # /usr/local/sbin/phpxs -s # cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini (agregar mysql) # pkg_add php4-mysql-4.3.8.tgz # /usr/local/sbin/phpxs -a mysql (agregar imap) # pkg_add php4-imap-4.3.8.tgz # /usr/local/sbin/phpxs -a imap (quitar mysql a manera de prueba) # pkg_delete php4-mysql-4.3.8 # /usr/local/sbin/phpxs -r mysql (instalar las librerías de PEAR) # pkg_add php4-pear-4.3.8.tgz
Leer la página del manual» packages(7)para mas información sobre paquetes binarios en OpenBSD.
También se puede compilar PHP a partir de fuentes utilizando el» árbol de portes. Sin embargo, esto sólo se recomienda para usuarios familiarizados con OpenBSD. El porte de PHP 4 está dividido en dos subdirectorios: core y extensions. El directorio extensions genera subpaquetes para todos los módulos soportados de PHP. Si se encuentra que no se desea crear alguno de estos módulos, utilice el sabor o FLAVORno_*. Por ejemplo, para evitar compilar el módulo imap, fijar el sabor o FLAVOR ano_imap.
Ediciones antiguas de OpenBSD utilizaban el sistema FLAVORS para compilar un PHP enlazado estáticamente. Dado que es difícil generar paquetes binarios utilizando este método, ahora es depreciado. Aún es posible utilizar los viejos árboles estables de ports si así se desea, pero carecen de soporte por parte del equipo de OpenBSD. Si se tiene algún comentario al respecto, el responsable actual del port es Anil Madhavapeddy (avsm arroba openbsd punto org).
Esta sección contiene notas y sugerencias específicas para la instalación de PHP en sistemasSolaris.
La instalacion Solariscarece con frecuencia de los compiladores de C y sus herramientas relacionadas. Lealas preguntas frecuentespara obtener información sobre porqué usar versiones GNU de algunas de estas herramientas.
Para descomprimir la distribución PHP se necesita
Para compilar PHP se necesita
Para compilar extensiones adicionales o hackear el código PHP puede que se necesite también
Se puede simplificar el procesao de intalación deSolarismediante el uso de pkgadd para instalar la mayoría de sus componentes necesarios. El Sistema de Empaquetado de Imagen (IPS) paraSolaris 11 Expresscontiene también la mayoría de los componentes requeridos para la instalación usando el comando pkg.
Esta sección contiene notas y consejos específicos para instalar PHP sobre» Debian GNU/Linux.
No se ofrece soporte de builds no oficiales de terceros. Cualquier bug debe ser informado al equipo de Debian a no ser que puedan reproducirse usando los últimos builds de nuestra» zona de descargas.
Mientras que las instrucciones para construir PHP sobre Unix se aplican a Debian también, esta página del manual contiene información específica para otras opciones, tales como utilizar ya sea los comandosapt-getoaptitude. En esta página del manual estos dos comandos se pueden utilizar indistintamente.
Primero, nótese que otros paquetes relacionados podrían ser deseables comolibapache2-mod-php5para integración con Apache 2, yphp-pearpara PEAR.
Segundo, antes de instalar un paquete, es sensato asegurarse de que la lista de paquetes está al día. Típicamente, esto se realiza ejecutando el comandoapt-get update.
Ejemplo #1 Ejemplo de Instalación en Debian con Apache 2
# apt-get install php5-common libapache2-mod-php5 php5-cli
APT instalará automáticamente el módulo PHP 5 para Apache 2 junto con todas sus dependencias, y luego lo activará. Apache debería reiniciarse para que los cambios tengan efecto. Por ejemplo:
Ejemplo #2 Deteniendo e iniciando Apache una vez que PHP está instalado
# /etc/init.d/apache2 stop # /etc/init.d/apache2 start
En la sección anterior, PHP se instaló únicamente con los módulos principales. Es muy probable que se deseen módulos adicionales, tales comoMySQL,cURL,GD, etc. Estos también pueden ser instalados vía el comandoapt-get.
Ejemplo #3 Métodos para listar paquetes relacionados con PHP 5
# apt-cache search php5 # aptitude search php5 # aptitude search php5 |grep -i mysql
Los ejemplos mostrarán una gran cantidad de paquetes incluyendo varios específicos a PHP como php5-cgi, php5-cli y php5-dev. Determine cuales son necesarios e instálelos como cualquier otro ya sea conapt-getoaptitude. Y ya que Debian realiza revisión de dependencias, preguntará por ellos, así que por ejemplo para instalar MySQL y cURL:
Ejemplo #4 Instalar PHP con MySQL, cURL
# apt-get install php5-mysql php5-curl
APT agregará automáticamente las líneas apropiadas a los diferentes ficheros relacionados conphp.inicomo/etc/php5/apache2/php.ini,/etc/php5/conf.d/pdo.ini, etc. y dependiendo de la extensión, le agregará registros similares aextension=foo.so. De cualquier manera, reiniciar el servidor web (como es Apache) es requerido antes de que estos cambios tengan efecto.
apt-getyaptitude. Pero, explicar las sutiles diferencias entre estos comandos va más allá del alcance de este manual.Esta sección contiene notas y sugerencias específicas para la instalación de PHP en Mac OS X. PHP se incluye con Mac, y la compilación es similar a laguía de instalación Unix.
Hay algunas versiones preempaquetadas y precompiladas de PHP para Mac OS X. Esto puede ayudar en la creación de una configuración estándar, pero si fuera necesario tener un conjunto diferente de características (como un servidor seguro, o un controlador de base de datos diferente), es posible que sea necesario construir PHP y/o un servidor web. Si no está familiarizado con la construcción y compilación de su propio software, vale la pena revisar si alguien ya ha construido una versión empaquetada de PHP con las características que necesita.
Los siguientes recursos ofrecen paquetes fáciles de instalar y binarios precompilados para PHP en Mac OS:
PHP está incluido en los Macs desde la versión OS X 10.0.0. Habilitar PHP con el servidor web por defecto requiere descomentar unas cuantas líneas en el fichero de configuración de Apachehttpd.confdondeCGIy/oCLIestán activados por defecto (son fácilmente accesibles a través del programa Terminal).
Siguiendo las instrucciones que se ofrecen a continuación se podrá habilitar PHP de una forma rápida para un entorno de desarrollo local. Esmuy recomendabletener siempre actualizado PHP a la última versión. Como casi todo el software vivo, y PHP no es una excepción, se crean nuevas versiones para resolver errores y añadir nuevas funcionalidades. Consulte la documentación de instalación de Mac OS X adecuada para más detalles. Las siguientes instrucciones para obtener una configuración están orientadas a los principiantes que deseen obtener una configuración totalmente operativa. Se anima a todos los usuarios a compilar o instalar una nueva versión ya empaquetada.
La instalación típica es mediante mod_php. Para habilitar el paquete mod_php que viene en el Mac OS X para el servidor web Apache (el servidor web por defecto, al que se puede acceder mediante las Preferencias del Sistema) se requiere efectuar los siguientes pasos:
Findero elSpotlightpuede ser algo complicado encontrar dicho fichero ya que por defecto es privado y pertenece al usuarioroot.Nota:Una forma de abrir el fichero es usando un editor de texto basado en UNIX en el Terminal, como por ejemplo
nano. Debido a que el fichero pertenece al usuariorootse debe emplear el comandosudopara abrirlo (como si fueramos el usuarioroot). Por ejemplo, teclée lo siguiente en elTerminal(tras lo cual le preguntará por la contraseña):sudo nano /private/etc/apache2/httpd.confComandos de nano a tener en cuenta:^w(buscar),^o(guardar), and^x(salir) donde^representa la tecla Ctrl.
Nota:Las versiones de Mac OS X anteriores a 10.5 tienen incorporadas versiones antiguas de PHP y Apache. Por ello, es posible que el fichero de configuracion de Apache se encuentre en dichos equipos en/etc/httpd/httpd.conf.
En el editor de texto, descomente las líneas (eliminando el símbolo #) que sean similares a las que se muestran a continuación (a menudo estas líneas se encuentran separadas, asi que tendrá que localizar ambas en el fichero):
# LoadModule php5_module libexec/httpd/libphp5.so # AddModule mod_php5.c
Asegúrese que las extensiones que desee puedan ser interpretadas como PHP (por ejemplo: .php .html y .inc)
Como las siguientes sentencias ya existían en elhttpd.conf(desde el Max Panther), una vez se habilite PHP los ficheros.phpautomáticamente seran interpretados como PHP.
<IfModule mod_php5.c>
# If php is turned on, we respect .php and .phps files.
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps
# Since most users will want index.php to work we
# also automatically enable index.php
<IfModule mod_dir.c>
DirectoryIndex index.html index.php
</IfModule>
</IfModule>
Nota:
Con anterioridad a OS X 10.5 (Leopard) se empaquetaba PHP 4 en lugar de PHP 5, en cuyo caso las instrucciones anteriores pueden ser ligeramente diferentes cambiando los 5 por los 4.
DocumentRootÉste es el directorio raíz de todos los ficheros web. Los ficheros en este directorio son obtenidos del servidor web a fin de que los ficheros PHP sean ejecutados como PHP antes de ser enviados al navegador. Una ruta de acceso típica es/Library/WebServer/Documentspero puede ser configurada enhttpd.conf. Como alternativa, elDocumentRootpor defecto para usuarios individuales es/Users/yourusername/SitesLa funciónphpinfo()muestra información sobre PHP. Considere la creación de un fichero en el DocumentRoot que contenga el siguiente código PHP:
<?php phpinfo();?>Para reiniciar, ejecutesudo apachectl gracefulen el shell o desactive/active la opción "Compartir Web" en las Preferencias del Sistema. Por defecto, cargar ficheros locales en el navegador tiene unaURLparecida a:http://localhost/info.php. Usar DocumentRoot en el directorio del usuario es otra opción, y la URL sería parecida a:http://localhost/~yourusername/info.php
CLI(oCGIen versiones antiguas) también es llamado de forma correctaphpy posiblemente existe como/usr/bin/php. Abra el Terminal, lea lasección de línea de comandodel manual de PHP, y ejecutephp -vpara comprobar la versión de PHP del binario PHP. Una llamada aphpinfo()también le mostrará esta información.
Instalación de PHP en sistemas modernos de Microsoft Windows y configuración recomendada con servidores web comunes.
Las versiones oficiales de PHP en Windows se recomiendan para su uso en producción. Sin embargo, puede construir PHP desde el código fuente. Necesitará un entorno de Visual Studio. Veáse» las instrucciones de construcción paso a paso.
Uso de PHP en la línea de comandos en WindowsInstalación de PHP en Azure App Services(aka Microsoft Azure, Windows Azure, o (Windows) Azure Web Apps).
PHP requiere al menos Windows 2008/Vista. Ya sea 32 bits o 64 bits (AKAX86 o X64. PHP no se ejecuta en Windows RT/WOA/ARM). A partir de PHP 7.2.0 Windows 2008 y Vista ya no son soportados.
PHP requiere Visual C runtime (CRT). Muchas aplicaciones lo requieren por lo que ya esté instalado.
El Microsoft Visual C++ Redistributable para Visual Studio 2019 es adecuado para todas las versiones de PHP, véase» https://visualstudio.microsoft.com/downloads/.
Debes descargar la biblioteca x86 CRT para compilar PHP para arquitecturas x86 y x64 CRT para compilar de PHP x64.
Si CRT ya está instalado, el instalador te lo dirá y no cambiará nada.
El instalador de CRT admite los modificadores de línea de comandos /quiet y /norestart, por lo que puede ejecutar un script.
Las extensiones PECL están preconstruidas para Windows y están disponibles en:» http://windows.php.net/downloads/pecl/releases/
Algunas extensiones usan características específicas de algunos sistemas Unix y, por lo tanto, no están disponibles en Windows. Por lo demás, todas las extensiones están disponibles para Windows.
Si quiere configurar PHP y está usando IIS, la forma más fácil es usar» El instalador de la plataforma web de Microsoft (WebPI).
» XAMPP, WampServer y BitNami configurarán las aplicaciones PHP para su uso con Apache en Windows.
La configuración de Nginx en Windows requiere un poco más de configuración. Vea la» documentación de Nginxpara obtener ayuda adicional con la configuración.
Se recomienda habilitar OpCache. Esta extensión está incluida en PHP para Windows. Compila y optimiza scripts de PHP y los almancena en memoria caché para así no tener que compilarlos cada vez que se cargue la página.
En el php.ini, establezca
Ejemplo #1 Configuración recomendada de WinCache
zend_extension=php_opcache.dll opcache.enable=On opcache.cli_enable=On
Se recomineda que se use WinCache si se utiliza IIS, especialmente en un entorno de alojamiento web compartido o si se utuliza el almacenamiento de ficheros en red (NAS). Tenga en cuenta que WinCache ya no es compatible con PHP 8.0.0. Todas las aplicaciones de PHP se benefician automáticamente de la funcionalidad de almancenamiento en caché de WinCache. Las operaciones en el sistema de ficheros se almacenan en memoria caché. WinCache también puede almacenar en memoria caché objetos de usuario y compartirlos entre procesos dephp.exeophp-cgi.exe(objetos compartidos entre peticiones). Muchas de las grandes aplicaciones web tienen un complemento, extensión u opción de configuración para hacer uso de la caché de objetos de usuario de WinCache. Si lo que necesita es un alto rendimiento, debería utilizar la caché de objetos en sus aplicaciones. Véase:» http://pecl.php.net/package/WinCachepara descargar una DLL (o tgz) de WinCache a su directorio de extensiones de PHP (extensions_dir en el php.ini). En el php.ini, establezca
Ejemplo #2 Configuración recomendada de WinCache
extension=php_wincache.dll wincache.fcenabled=1 wincache.ocenabled=1 ; eliminado a partir de 2.0.0.0
En el Administrador de IIS, Instalar módulo FastCGI y añadir un manejador para`.php`a la ruta dePHP-CGI.exe(no dePHP.exe)
Puede usear la herramienta de línea de comandos APPCMD para configurar IIS.
Probablemente necesitará un servidor de bases de datos. Las bases de datos populares proporcionan extensiones de PHP para utillzarlas. Si su sitio web no tiene mucho tráfico, puede ejecutar el servidor de bases de datos en su mismo servidor web. Muchos servidores de bases de datos se ejecutan en Windows.
PHP incluye las extensiones mysqli y pdo_mysql.
IIS está integrado en Windows. En Windows Server, use Server Manager para añadir el rol de IIS. Asegúrese de incluir CGI Role Feature. En Windows Desktop, use Añadir/Eliminar Programas del Panel de Control para añadir IIS. La documentación de Microsoft tiene» instrucciones detallas. Para aplicaciones web de escritorio y desarrollo web, también se puede usar IIS/Express o PHP Desktop.
Ejemplo #1 Linea de órdenes para configurar IIS y PHP
@echo off REM Descargar el fichero .ZIP o la compilación de PHP desde http://windows.php.net/downloads/ REM REM Ruta al directorio donde se ha descomprimido el fichero .ZIP de PHP set phpdir=c:\php REM Limpiar los manejadores actuales de PHP %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI REM El siguiente comando generará un mensaje de error si PHP no está instalado. Esto puede ser ignorado. %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI'] REM Instalar el manejador de PHP %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe'] %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified'] %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script REM Configurar las variables de FastCGI %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000 %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']" %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"
Existen varias compilaciones de Apache2 para Windows. Se recomiendan las compilaciones Apache de ApacheLounge, aunque otras opciones pueden ser XAMPP, WampServer y BitNami, las cuales proporcionan herramientas de instalación automática. Se puede utilizar mod_php o mod_fastcgi para cargar PHP en Apache. Si se emplea mod_php, se DEBE utilizar una compilación TS de Apache construida con la misma versión de Visual C y la misma CPU (x86 o x64).
Descargue las versiones de producción de PHP desde» http://windows.php.net/download/. Todas las compilaciones están optimizadas (PGO), y las versiones de QA y GA se prueban exhaustivamente.
Existen 4 tipos de compilación de PHP:
Thread-Safe(TS) - usada para servidores web monoproceso, como Apache con mod_php
Non-Thread-Safe(NTS) - usada para IIS y otros servidores web FastCGI (Apache con mod_fastcgi) y la recomendad para scripts de línea de comandos
x86 - para sistemas de 32-bits.
x64 - para sistemas de 64 bits.
Este capítulo enseña cómo compilar PHP a partir del código fuente en Windows, utilizando las herramientas de Microsoft. Para compilar PHP con cygwin, consulte la instalación de unix.Instalación sobre sistemas Unix.
Veáse la documentación Wiki en:» https://wiki.php.net/internals/windows/stepbystepbuild
Esta sección contiene notas y sugerencias específicas para conseguir ejecutar PHP en la línea de comandos para Windows.
Nota:
Se debe leer primero elmanual de instalación PHP en Windows
Conseguir ejecutar PHP desde la línea de comandos sin hacer ningún cambio a Windows.
C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3
Pero hay algunos pasos sencillos que puede seguir para hacer esto simple. Algunas de estas medidas ya se deberían haber tomado, pero se repiten aquí para ser capaz de proporcionar una completa secuencia paso a paso.
Nota:
TantoPATHcomoPATHEXTson variables de sistema preexistentes importantes en Windows, por lo que se ha de asegurarse de no sobrescribir dichas variables, solamente agregarle algo.
Añada la ubicación del ejecutable de PHP (php.exe,php-win.exeophp-cli.exedependiendo de su versión de PHP y las preferencias de presentación) a la variable de entornoPATH. Lea más acerca de cómo añadir el directorio de PHPPATHen laentrada correspondiente de preguntas frecuentes.
Añada la extensión.PHPde la variable de entornoPATHEXT. Esto se puede hacer al mismo tiempo, con la modificación de la variable de entornoPATH. Siga los mismos pasos como se describe en lasPreguntas frecuentespero habría que modificar la variable de entornoPATHEXTen lugar de la variable de entornoPATH.
Nota:
La posición en que se coloca el
.PHPdetermina qué secuencia de comandos o programa se ejecuta cuando hay nombre de archivos coincidentes. Por ejemplo, colocar.PHPantes de.BAThará que el script se ejecute, en lugar de el archivo por lotes, si hay un fichero por lotes con el mismo nombre.
Asociar la extensión.PHPcon un tipo de fichero. Esta se hace ejecutando el siguiente comando:
assoc .php=phpfile
Asociar el tipo de ficherophpfilecon el adecuado ejecutable PHP. Esto se hace ejecutando el siguiente comando:
ftype phpfile="C:\PHP5\php.exe" -f "%1" -- %~2
Si sigue estos pasos permitirá ejecutar scripts PHP desde cualquier directorio sin necesidad de escribir el ejecutable PHP o la extensión.PHPy todos los parámetros, será enviada a el script para el procesamiento.
En el ejemplo a continuación se detallan algunos de los cambios de registro que se puede hacer manualmente.
Ejemplo #1 Registro de cambios
Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php] @="phpfile" "Content Type"="application/php" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile] @="PHP Script" "EditFlags"=dword:00000000 "BrowserFlags"=dword:00000008 "AlwaysShowExt"="" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon] @="C:\\php\\php-win.exe,0" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell] @="Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open] @="&Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command] @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"
Con estos cambios el mismo comando se puede escribir como:
"C:\PHP Scripts\script" -arg1 -arg2 -arg3
"C:\PHP Scripts"está en el variable de entornoPATH:script -arg1 -arg2 -arg3
Nota:
Hay un pequeño problema si tiene intención de utilizar esta técnica y usar scripts PHP como filtro de línea de comandos, como el ejemplo a continuación:
odir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3Es posible que el script simplemente se cuelga y no salga nada. Para hacer esto operacional, es necesario hacer otro cambio en el registro.dir | script -arg1 -arg2 -arg3Información adicional sobre este tema se pueden encontrar en el» Artículo de la base de conocimientos de Microsoft: 321788. A partir de Windows 10, este ajuste parece haber sido invertido, haciendo que la instalación predeterminada de Windows 10 admita manejadores de consola heredados automáticamente. Esta» entrada del foro de Microsoftproporciona la explicación.Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer] "InheritConsoleHandles"=dword:00000001
Esta sección contiene notas y sugerencias específicas de Apache 2.x instaladas con PHP en sistemas Microsoft Windows.
Nota:
Se debe leer primero elmanual de instalación PHP en Windows
Se recomienda consultar la» Documentación de Apachepara obtener un conocimiento básico del servidor Apache 2.x. También considere leer las» notas específicas para Windowspara Apache 2.x antes de seguir leyendo.
Descargue la versión más reciente de» Apache 2.xy una versión adecuada de PHP. Siga los pasos delmanual de instalacióny regrese para continuar con la integración de PHP y Apache.
Hay tres formas de configurar PHP para que funcione con Apache 2.x en Windows. PHP se puede ejecutar como controlador, como CGI o bajo FastCGI
Nota:Recuerde que cuando agrega rutas como valores en los archivos de configuración de Apache en Windows, todas las barras invertidas tal comoc:\directory\file.extdeberían ser convertidas en barras comunes:c:/directory/file.ext. Una barra común al final será necesaria para directorios.
Para cargar el módulo PHP en Apache 2.x las siguientes líneas en el fichero de configuraciónhttpd.confde Apache deben ser añadidas:
Ejemplo #1 PHP y Apache 2.x como controlador
# LoadModule php8_module "c:/php/php8apache2_4.dll" AddHandler application/x-httpd-php .php # configure the path to php.ini PHPIniDir "C:/php"
Nota:Recuerde, la ruta real de PHP debe sustituirse porC:/php/en los ejemplos anteriores. Asegúrese que el fichero al que hace referencia en la directiva LoadModule está en la ubicación especificada, y utilizephp7apache2_4.dllpara PHP 7, ophp8apache2_4.dllpara PHP 8.
The above configuration will enable PHP handling of any file that has a .php extension, even if there are other file extensions. For example, a file namedexample.php.txtwill be executed by the PHP handler. To ensure that only files thatend in.phpare executed, use the following configuration instead: La configuración anterior permitirá el manejo de PHP de cualquier fichero que contenga la extensión .php, incluso si hay otras extensiones de fichero. Por ejemplo, el fichero llamadoexample.php.txtserá ejecutado por el controlador PHP. Para garantizar que solo se ejecuten los ficheros queterminen en.php, utilice la siguiente configuración:
<FilesMatch \.php$>
SetHandler application/x-httpd-php
</FilesMatch>Se recomienda consultar la» documentación de Apache CGIpara una comprensión más completa de la ejecución de CGI en Apache.
Para ejecutar PHP como CGI, deberá colocar los ficheros php-cgi en un directorio designado como directorio CGI utilizando la directiva ScriptAlias.
Será necesario colocar una línea#!en los ficheros PHP, que apunte a la ubicación del binario PHP:
Ejemplo #2 PHP y Apache 2.x como CGI
#!C:/php/php.exe <?php phpinfo(); ?>
Al usar el modo CGI, su servidor esta expuesto a diferentes ataques. Por favor, leer la secciónSeguridad con CGIpara aprender cómo defenderse de estos ataques.
Ejecutar PHP bajo FastCGI tiene una serie de ventajas con respecto a ejecutarlo bajo CGI. Configurarlo de esta manera es bastante sencillo:
Descarguemod_fcgiddesde» https://www.apachelounge.com. Los binarios de Win32 están disponibles para descargar desde ese sitio. Instale el módulo de acuerdo con las instrucciones que lo acompañarán.
Configure su servidor web como se muestra a continuación, teniendo cuidado de ajustar cualquier ruta que reflejen la forma en que ha instalado las cosas en su sistema particular:
Ejemplo #3 Configurar Apache para ejecutar PHP como FastCGI
LoadModule fcgid_module modules/mod_fcgid.so # ¿Dónde está el fichero php.ini? FcgidInitialEnv PHPRC "c:/php" AddHandler fcgid-script .php FcgidWrapper "c:/php/php-cgi.exe" .php
Clic derecho en el directorio temporal con el Explorador de archivos para mostrar los permisos.
Para IIS, compruebe que el usuario IIS_User posee el permiso MODIFY. Se puede saber cuál es el directorio temporal a través de la configuración o información de php.
PHP instalará en la nube. A la nube de PHP!
PHP instalará el Azure cloud platform.
Ver acerca de Azure SDK para PHP.
FPM (FastCGI Process Manager) es una implementación alternativa al PHP FastCGI con algunas características adicionales (la mayoría) útiles para sitios web con mucho tráfico.
Estas características incluyen:
Manejo avanzado para detener/arrancar procesos de forma fácil;
Posibilidad de iniciar hilos de procesos con diferentes uid/gid/chroot/environment, escuchar en diferentes puertos y usar distintos php.ini (remplazando); safe_mode
Registro stdout y stderr;
Reinicio de emergencia en caso de destrucción accidental del caché opcode;
Soporte acelerado de subidas;
"slowlog" - scripts de registro de procesos (no sólo sus nombres, sin sus backtraces también, usando ptrace y similares para leer procesos execute_data remotos) que son inusualmente lentos;
fastcgi_finish_request()- Función especial para detener y descargar todos los datos mientras continua haciendo algún proceso más largo (conversión de vídeos, procesamiento de estadísticas, etc.);
Creación dinámico/estático de hilos;
Información básica del status SAPI (similar al mod_status de Apache);
Basado en archivos de configuración php.ini
Para habilitar FPM en la construcción de PHP, debe añadirse--enable-fpma la línea de configuración.
Hay otras opciones de configuración específicas de FPM (todas ellas optativas):
--with-fpm-user- Establecer el usuario de FPM (por omisión: nobody).
--with-fpm-group- Establecer el grupo de FPM (por omisión: nobody).
--with-fpm-systemd- Activar la integración del sistema (por omisión: no).
--with-fpm-acl- Utilizar las listas de control de acceso de POSIX (por omisión: no). Desde 5.6.5
FPM usa la sintaxis dephp.inipara su fichero de configuración -php-fpm.conf, y agrupa ficheros de configuración.
pidstringRuta al fichero PID. Valor por defecto: none.
error_logstringRuta al fichero de registro de errores. Valor por defecto:#INSTALL_PREFIX#/log/php-fpm.log. Si se establece a "syslog", los registros son enviados a syslogd en lugar de escribir en un archivo local.
log_levelstringNivel de registro de errores. Posibles valores: alert, error, warning, notice, debug. Valor por defecto: notice.
log_limitintLímite de registro para las líneas registradas que permite registrar mensajes de más de 1024 caracteres sin envolver. Valor por defecto: 1024. Disponible a partir de PHP 7.3.0.
log_bufferingboolRegistro experimental sin almacenamiento adicional en el búfer. Valor por defecto: sí. Disponible a partir de PHP 7.3.0.
syslog.facilitystringUsado para especificar qué tipo de programa está recibiendo los mensajes de registro. Valor por defecto: daemon.
syslog.identstringAnteponer a cada mensaje. Si hay varias instancias FPM ejecutándose en el mismo servidor, puede cambiar el valor por defecto que debe adaptarse a sus necesidades. Valor por defecto: php-fpm.
emergency_restart_thresholdintSi este número de procesos termina con SIGSEGV o SIGBUS dentro del intervalo de tiempo establecido poremergency_restart_intervalentonces FPM se reiniciará. Un valor de 0 corresponde a 'Off'. Valor por defecto: 0 (Off).
emergency_restart_intervalmixedIntervalo de tiempo usado poremergency_restart_intervalpara determinar cuando un reinicio agraciado será realizado. Esto puede ser útil trabajar sobre corrupciones accidentales in en acelerador de memoria compartida. Unidades disponibles:: s(segundos), m(inutos), h(oras), o d(ías). Unidad por defecto: segundos. Valor por defecto: 0 (Off).
process_control_timeoutmixedLímite de tiempo que un hilo de proceso espera por una señal maestra. Unidades disponibles: s(egundos), m(inutos), h(oras), o d(ías) Unidad por defecto: segundos. Valor por defecto: 0.
process.maxintEl número máximo de procesos FPM creará. Esto ha sido diseñado para controlar el número global de procesos cuando se utiliza PM dinámico dentro de muchos pools. Utilícelo con precaución. Valor por defecto: 0.
process.priorityintEspecifique la prioridad nice(2) que se aplicará al proceso maestro (sólo si se establece). El valor puede variar entre -19 (prioridad más alta) hasta 20 (prioridad más baja). Valor por defecto: no establecido.
daemonizebooleanEnvía a FPM al background. Establezca a 'no' para mantener FPM en foreground para depuración. Valor por defecto: yes.
rlimit_filesintEstablece el descriptor rlimit de archivos abiertos para el proceso maestro. Valor predeterminado: Establece el descriptor rlimit de archivos abiertos para el proceso maestro.
rlimit_coreintEstablece el tamaño máximo del núcleo rlimit para el proceso maestro. Valor por defecto: 0.
events.mechanismstringEspecifica el mecanismo de eventos que FPM utilizará. Los siguientes están disponibles: select, pool, epoll, kqueue (*BSD), port (Solaris). Valor por defecto: no establecido (auto-detección).
systemd_intervalintCuando FPM es compilado con integración con systemd, especifique el intervalo, en segundos, entre notificaciones de reporte de salud a systemd. Coloque a 0 para deshabilitar. Valor por defecto: 10.
Con FPM usted puede correr varios grupos de procesos con diferentes ajustes. Estos son los parámetros que pueden ser ajustados por grupo.
listenstringLa dirección sobre la cual desea aceptar peticiones FastCGI. Las sintaxis válidas son: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. Esta opción es obligatoria por cada grupo.
listen.backlogintEstablece listen(2) backlog. Un valor de '-1' significa ilimitado. Valor por defecto: -1.
listen.allowed_clientsstringLista de direcciones ipv4 de clientes FastCGI que tienen permiso para conectarse. El equivalente a la variable de entorno FCGI_WEB_SERVER_ADDRS en el PHP FastCGI (5.2.2+) original. Tiene sentido solamente con un socket tcp escuchando. Cada dirección debe ser separada por coma. Si este valor es dejado en blanco, las conexiones serán aceptas desde cualquier dirección ip. Valor por defecto: any.
listen.ownerstringEstablece permisos para sockets unix, si uno es usado. En Linux, los permisos de lectura/escritura deben ser puestos a fin de permitir conexiones desde un servidor web. Muchos sistemas derivados de BSD permiten conexiones sin considerar los permisos. Valor por defecto: usuario y grupo son establecidos según el usuario ejecutor, permisos puestos a 0660.
listen.groupstringVerlisten.owner.
listen.modestringVerlisten.owner.
listen.acl_usersstringCuando las lsitas de control de acceso POSIX están soportadas, usted puede configurarlas usando esta opción. Cuando se establece,listen.ownerylisten.groupson ignoradas. El valor es una lista de nombres de usuario separado por comas. Desde PHP 5.6.5.
listen.acl_groupsstringVerlisten.acl_users. El valor es una lista de nombres de grupo separado por comas. Desde PHP 5.6.5.
userstringUsuario Unix de procesos FPM. Esta opción es obligatoria.
groupstringGrupo Unix group of FPM processes. Si no es establecido, el grupo del usuario por defecto será usado.
pmstringSeleccione cómo el manejador de procesos controlará el número de hilos de procesos. Valores posibles:static,ondemand,dynamic. Esta opción es obligatoria.
static- el número de hilos de proceso es fijo (pm.max_children).
ondemand- el proceso se lanza en demanda (cuando se solicita, al contrario que dynamic, dondepm.start_serversson iniciados cuando el servicio está iniciado.
dynamic- el número de hilos de proceso será basado dinámicamente basado en las siguientes directivas:pm.max_children,pm.start_servers,pm.min_spare_servers,pm.max_spare_servers.
pm.max_childrenintEl número de hilos de procesos a ser creados cuandopmes puesto astaticy el máximo número de hilos de proceso a ser creados cuandopmes puesto adynamic. Esta opción es obligatoria.
Esta opción establece el límite sobre el número de peticiones simultaneas que serán servidas. Equivale a la directiva ApacheMaxClients con mpm_prefork y a la variable de entornoPHP_FCGI_CHILDRENdel PHP FastCGI original.
pm.start_serversintNúmero de hilos de procesos creados al inicio. Usado solamente cuandopmes puesto adynamic. Valor por defecto: min_spare_servers + (max_spare_servers - min_spare_servers) / 2.
pm.min_spare_serversintEl número mínimo deseado de procesos libres en el servidor. Usado sólo cuandopmes puesto adynamic. También obligatorio en este caso.
pm.max_spare_serversintEl número máximo deseado de procesos libres en el servidor. usado sólo cuandopmes puesto adynamic. También obligatorio en este caso.
pm.process_idle_timeoutmixedEl número de segundos después de los cuales se matará un proceso inactivo. Usado sólo cuandopmestá establecido comoondemand. Unidades disponibles: s(segundos)(predeterminado), m(inutos), h(horas), o d(ías). Valor por defecto: 10s.
pm.max_requestsintEl número de pedidos que cada hilo de proceso debe ejecutar antes de reaparecer. Esto puede ser útil para evitar las fugas de memoria en librerías de terceros. para el procesamiento de solicitudes sin límites especifique '0'. Equivale aPHP_FCGI_MAX_REQUESTS. Valor por defecto: 0.
pm.status_pathstringLa dirección URI para verla página de status FPM. Este valor debe comenzar con una barra inclinada (/). Si no se establece este valor, no se reconocerá ninguna URI como página de estado. Valor por defecto: ninguno. . Valor por defecto: none.
ping.pathstringLa dirección URI del ping para llamar a la página de monitor del FPM. Si este valor no es establecido, ninguna dirección URI será reconocida como página del ping. Esto debería ser usado para probar desde el exterior que el FPM está funcionando y respondiendo. Por favor, note que este valor debe empezar con un slash (/).
ping.responsestringEsta directiva puede ser usada para personalizar las peticiones de respuestas a ping. La respuesta es formateada como text/plain con un código de respuesta 200. Valor por defecto: pong.
process.priorityintEspecifique la prioridad nice(2) que se aplicará al proceso maestro (sólo si se establece). El valor puede variar entre -19 (prioridad más alta) hasta 20 (prioridad más baja). Valor por defecto: no establecido.
process.dumpableboolEstablece el indicador de proceso descargable (PR_SET_DUMPABLE prctl) incluso si el usuario o grupo del proceso o grupo es diferente al usuario del proceso maestro. Permite crear el proceso core dump y ptrace el proceso para el usuario del pool. Valor por defecto: no. Desde de PHP 7.0.29, 7.1.17 y 7.2.5.
prefixstringEstablece un prefijo para la ruta de evaluación
request_terminate_timeoutmixedEl tiempo de espera para servir una simple petición luego que el proceso worker sea eliminado. Esta opción debe ser usada cuando la opción 'max_execution_time' no detenga la ejecuciuón del script por cualquier razón. Un valor de '0' corresponde a 'Off'. Unidades disponibles: s(egundos)(por defecto), m(inutos), h(horas), or d(ías). Default value: 0.
request_slowlog_timeoutmixedEl tiempo de espera para servir una simple petición después de que un backtrace PHP sea volcado al fichero 'slowlog'. Un valor de '0' corresponde a 'Off'. Unidades disponibles: s(egundos)(por defecto), m(inutos), h(oras), or d(ías). Valor por defecto: 0.
slowlogstringEl fichero de registro para peticiones lentas. Valor por defecto:#INSTALL_PREFIX#/log/php-fpm.log.slow.
rlimit_filesintEstablece el fichero descriptor rlimit. Valor por defecto: definido por el sistema.
rlimit_coreintEstablece el tamaño máximo del rlimit. Valores posibles: 'unlimited' o un entero mayor o igualo a 0. Valor por defecto: definido por el sistema.
chrootstringEstablece el Chroot (enjaulado) a este directorio al inicio. Este valor debe ser definido como una ruta absoluta. Cuando este valor no es establecido, el chroot no es usado.
chdirstringEstablece el Chdir a este directorio al inicio. Este valor debe ser establecido como una ruta absoluta. Valor por defecto: directorio actual o / cuando está en chroot (enjaulado).
catch_workers_outputbooleanRedirige los worker stdout y stderr en el fichero de registro principal. Sí no es establecido, stdout y stderr serán redirigidos a /dev/null de acuerdo a las especificaciones FastCGI. Valor por defecto: no.
decorate_workers_outputboolHabilitar la decoración de salida para la salida de loscatch_workers_outputsi está activado. Valor por defecto: sí. Disponible a partir de PHP 7.3.0.
clear_envbooleanEntorno limpio in workers FPM. Evita que variables de entorno arbitrarias lleguen a los procesos FPM mediante la limpieza del entorno en los workers antes de que se añadan las variables env a las pools correspondientes a esta configuración. Desde PHP 5.4.27, 5.5.11, y 5.6.0. Valor por defecto: Yes.
security.limit_extensionsstringLimita las extensiones del script principal que FPM procesará. Esto puede evitar errores de configuración del lado del servidor. Usted debería limitar su FPM a procesar unicamente extensiones .php para evitar que usuarios malintencionados usen diferentes extensiones para ejecutar código PHP. Valor por defecto: .php .phar
access.logstringArchivo de registro de acceso. Valor por defecto: no establecido
access.formatstringFormato del archivo de registro de acceso. Valor por defecto: "%R - %u %t \"%m %r\" %s"
| Placeholder | Descripción |
|---|---|
%C | %CPU |
%d | duration µs |
%e | fastcgi env |
%f | script |
%l | content length |
%m | method |
%M | memory |
%n | pool name |
%o | header output |
%p | PID |
%q | query string |
%Q | the glue between %q and %r |
%r | request URI |
%R | remote IP address |
%s | status |
%T | time |
%t | time |
%u | remote user |
Es posible pasar las variables de entorno adicionales y actualizar los ajustes PHP de ciertos grupos. Para ello, se necesita agregar las siguientes opciones al fichero de configuración.
Ejemplo #1 Pasando variables de entorno y ajustando las configuraciones de PHP por grupos
env[HOSTNAME] = $HOSTNAME env[PATH] = /usr/local/bin:/usr/bin:/bin env[TMP] = /tmp env[TMPDIR] = /tmp env[TEMP] = /tmp php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com php_flag[display_errors] = off php_admin_value[error_log] = /var/log/fpm-php.www.log php_admin_flag[log_errors] = on php_admin_value[memory_limit] = 32M
php_valueophp_flagserán sobre-escritos a sus valores previos. Por favor note que definiendodisable_functionsodisable_classesno sobre-escribirá los valores de definiciones anterioresphp.ini, pero añadirán nuevos en cambio.Ajustes definidos conphp_admin_valueandphp_admin_flagcannot be anulados conini_set().
Como 5.3.3, establecer los ajustes PHP es también posible como servidor web.
Ejemplo #2 Establecer ajustes PHP en nginx.conf
set $php_value "pcre.backtrack_limit=424242"; set $php_value "$php_value \n pcre.recursion_limit=99999"; fastcgi_param PHP_VALUE $php_value; fastcgi_param PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";
Dado a que estos valores se pasan a php-fpm como cabeceras fastcgi, php-fpm no debe estar vinculado a una dirección accesible para todo el mundo. De lo contrario, cualquiera podría alterar las opciones de configuración de PHP. Ver tambiénlisten.allowed_clients.
Nota:Los pools no son un mecanismo de seguridad, porque no proporcionan una separación total; por ejemplo, todos los pools utilizarían una única instancia de OPcache.
» PECLes un repositorio de extensiones de PHP disponible mediante el sistema de paquetes» PEAR. Esta sección del manual tiene por objetivo ilustrar cómo obtener e instalar extensiones PECL.
Estas instrucciones asumen que la ruta al fuente de su distribución de PHP es/your/phpsrcdir/, y queextnamees el nombre de la extensión PECL. Ajuste a sus valores. Estas instrucciones, además, asumen conocimientos del» comando pear. La información del manual de PEAR para el comandopeartambién es aplicable al comandopecl.
Para poder usarse, una extensión compartida se debe construir, instalar, y cargar. Los métodos descritos abajo le proporcionan varias instrucciones para construir e instalar extensiones, pero no se cargarán automáticamente. Éstas se pueden cargar añadiendo una directivaextension. al ficherophp.ini, o bien mediante el uso de la funcióndl().
Al construir un módulo PHP, es importante contar con las versiones correctas de las herramientas requeridas (autoconf, automake, libtool, etc.). Para conocer los detalles de las herramientas requeridas y sus versiones, revise las» Instrucciones de Git Anónimo.
Existen varias opciones para descargar extensiones PECL, a saber:
pecl install extnamedescarga el código de la extensión automáticamente, de modo que en este caso no se hace necesario realizar una descarga por separado.pecl download extnamePuede descargar e instalar las extensiones PECL listadas en el sitio web de PECL usando el» comando pecl. También se podrán especificar versiones concretas.Dispone de dos formas para cargar extensiones PHP en Windows: o bien compilándolas en PHP, o bien cargando su DLL. El método recomendado y más sencillo es cargar una extensión pre-compilada.
Para cargar una extensión, debe estar disponible como fichero ".dll" en su sistema. Todas las extensiones son compiladas por el Grupo PHP automática y periódicamente (revise la siguiente sección para realizar descargas).
Para compilar una extensión en PHP, por favor, acceda a la documentación deconstrucción de la fuente.
Para compilar una extensión independiente (o lo que es lo mismo, un fichero DLL), por favor, revise la documentación deconstrucción de la fuente. Si el fichero DLL no está disponible ni en su distribución de PHP ni en PECL, deberá compilarla antes de poder comenzar a usarla.
Las extensiones de PHP generalmente se llaman "php_*.dll" (donde el asterisco representa el nombre de la extensión) y se localizan bajo la carpeta "PHP\ext".
PHP se distribuye con las extensiones más útiles para la mayoría de desarrolladores. Se les llama extensiones del "núcleo".
En cualquier caso, si necesita una funcionalidad que no proporciona ninguna de las extensiones del núcleo, podrá buscarla en PECL. La Biblioteca de la Comunidad de Extensiones de PHP (PECL) es un repositorio de extensiones PHP, que proporciona un directorio de todas las extensiones conocidas, y aloja utilidades para descargar y desarrollar extensiones de PHP.
Si usted ha desarrollado una extensión para su propio uso, quizá quiera considerar alojarla en PECL, de forma que otros desarrolladores con las mismas necesidades puedan verse beneficiados de su tiempo. Una de las ventajas es que tendrá la oportunidad de recibir colaboración, (ojalá) agradecimientos, informes de errores, e incluso parches/correcciones. Antes de enviar su extensión para ser alojada en PECL, por favor, lea» el envío a PECL.
A menudo, encontrará varias versiones de cada DLL:
etc.Debe tener en cuenta que los ajustes de su extensión deben coincidir con la configuración del ejecutable de PHP que está utilizando. El siguiente script de PHP le dirátodosobre sus ajustes de PHP:
Ejemplo #1 llamada aphpinfo()
<?php
phpinfo();
?>O ejecute desde la línea de comandos:
drive:\\path\to\php\executable\php.exe -i
La forma más común de cargar una extensión PHP consiste en incluirla en el fichero de configuraciónphp.ini. Por favor, tenga en cuenta que ya hay muchas extensiones presentes en el ficherophp.iniy que sólo es necesario eliminar el punto y coma para activarlas.
Observe que en versiones de PHP 7.2.0 y superiores, se podría utilizar el nombre de extensión en lugar del nombre de fichero de la extensión. Ya que esto es independiente del SO y más sencillo, especialmente para recién llegados, se convierte en la forma recomendada de especificar estensiones a cargar. El soporte para nombres de ficheros permanece por compatibilidad con versiones anteriores.
;extension=php_extname.dll
extension=php_extname.dll
; On PHP version 7.2 and up, prefer : extension=extname zend_extension=another_extension
Sin embargo, algunos servidores web puede resultar confusos, dado que no utilizan elphp.iniubicado junto al ejecutable de PHP. Para averiguar dónde se localiza elphp.inien uso, consulte su ruta usandophpinfo():
Configuration File (php.ini) Path C:\WINDOWS
Loaded Configuration File C:\Program Files\PHP\5.2\php.ini
Tras activar una extensión, guarde el ficherophp.ini, reinicie el servidor web y vuelva a comprobarphpinfo(). La nueva extensión debe ahora tener su propia sección.
Si la extensión no aparece enphpinfo(), compruebe los registro de errores para conocer qué provoca el problema.
Si está utilizando PHP desde la línea de comandos (CLI), podrá leer directamente en pantalla el error en la carga de la extensión.
Si está usando PHP en un servidor web, la localización y formato de los registros vería en función de su software. Por favor, lea la documentación de su servidor web para localizar los registros, dado que esto no lo gestiona el propio ejecutable de PHP.
Los problemas más comunes son la ubicación del fichero DLL, el valor de "extension_dir" enphp.ini, y desajustes de configuración en tiempo de compilación.
Si el problema reside en desajustes de configuración en tiempo de compilación, seguramente se deba a que no se ha descargado el fichero DLL correcto. Pruebe a descargar de nuevo la extensión con los ajustes correctos. De nuevo,phpinfo()puede resultar de gran ayuda.
PECL facilita la creación de extensiones PHP compartidas. Usando el» comando pecl, haga lo siguiente:
Esto descargará el código fuente deextname, lo compilará, e instalaráextname.soen suextension_dir. Ahora se puede cargarextname.somediantephp.ini
Por omisión, el comandopeclno instalará paquetes marcados en los estadosalphaobeta. Si no hay paquetes disponibles en estadostable, podrá instalar un paquete en estadobetautilizando el siguiente comando:
Del mismo modo, podrá también instalar una versión en concreto usando esta variante:
Nota:
Tras activar la extensión enphp.ini, será necesario reiniciar el servidor web para hacer efectivos los cambios.
A menudo no es posible utilizar el instaladorpecl. Esto se puede deber a que se encuentra tras un cortafuegos, o a que la extensión que trata de instalar no está disponible como paquete compatible con PECL, como por ejemplo extensiones no liberadas desde el SVN. Si necesita construir una extensión de este tipo, puede llevar a cabo esta tarea manualmente utilizando las herramientas de construcción de bajo nivel.
El comandophpizese utiliza para preparar el entorno de compilación de la extensión de PHP. En el siguiente ejemplo, el fuente de una extensión se ubica en un directorio llamadoextname:
$ cd extname $ phpize $ ./configure $ make # make install
En caso de que la instalación sea correcta, se crearáextname.soy se salvará en eldirectorio de extensionesde PHP. Quizá necesite ajustar el ficherophp.iniy añadir una líneaextension=extname.soantes de poder usar la extensión.
Si el sistema no contiene el comandophpize, y se están utilizando paquetes pre-compilados (como RPM), asegúrese de instalar también la versión de desarrollo apropiada del paquete PHP, dado que a menudo incluyen el comandophpizecon los ficheros de cabeceras necesarios para construir PHP y sus extensiones.
Ejecutephpize --helppara mostrar información de uso adicional.
php-config es una utilidad de consola que permite obtener información sobre la configuración de la instalación de PHP.
A la hora de compilar extensiones, si se tuvieran varias versiones de PHP instaladas, se podrá especificar sobre cuál se va a construir usando el modificador--with-php-configdurante la configuración, donde especificaremos la ruta a su respecto script php-config.
En cualquier momento podrá consutlarse la lista de opciones de la utilidad php-config ejecutando php-config con el modificador-h:
Usage: /usr/local/bin/php-config [OPTION] Options: --prefix [...] --includes [...] --ldflags [...] --libs [...] --extension-dir [...] --include-dir [...] --php-binary [...] --php-sapis [...] --configure-options [...] --version [...] --vernum [...]
| Opción | Descripción |
|---|---|
| --prefix | Prefijo del directorio donde PHP está instalado, p.ej. /usr/local |
| --includes | Lista de opciones -I con todos los ficheros incluídos |
| --ldflags | Banderas LD con las que se ha compilado PHP |
| --libs | Bibliotecas extras con las que se ha compilado PHP |
| --extension-dir | Directorio en el que se buscan por omisión las extensiones |
| --include-dir | Prefijo de directorio donde se buscan por omisión los ficheros de cabeceras |
| --php-binary | Ruta completa al binario de php CLI o CGI |
| --php-sapis | Muestra todos los módulos SAPI disponibles |
| --configure-options | Opciones de configuración para recrear la configuración de la instalación actual de PHP |
| --version | Versión de PHP |
| --vernum | Versión de PHP en forma de entero |
Quizá necesite construir una extensión PECL estáticamente en su binario de PHP. Para hacer esto, necesitará ubicar el fuente de la extensión bajo el directorio/su/directorio_fuentes_php/ext/e indicarle al sistema de construcción de PHP que regenere su script de configuración.
$ cd /your/phpsrcdir/ext $ pecl download extname $ gzip -d < extname.tgz | tar -xvf - $ mv extname-x.x.x extname
Esto generará el siguiente directorio:
Desde aquí, fuerce a PHP a regenerar el script de configuración, y entonces construya PHP con normalidad:
Nota:Necesitará autoconf 2.13 y automake 1.4+ para ejecutar el script 'buildconf' (es posible que funcionen versiones más recientes de autoconf, pero no están oficialmente soportadas).
Dependiendo de la extensión, utilizará--enable-extnameo--with-extname. Las extensiones que no requieren de bibliotecas externas generalmente utilizan--enable. Para asegurarse, ejecute el siguiente comando después de buildconf:
Algunos problemas son más comunes que otros. Los más comunes se enumeran en lasPreguntas frecuentes de PHPde este manual.
Si sigue bloqueado, seguramente alguien de la lista de correo de la instalación de PHP podrá ayudarle. Primero, debería consultar el archivo para comprobar si alguien ya ha contestado a otra persona que haya tenido el mismo problema. Los archivos están disponibles desde la página de soporte en» https://www.php.net/support.php. Para subscribirse a la lista de correo de la instalación de PHP (en inglés), envíe un correo vacío a» php-install-subscribe@lists.php.net. La dirección de la lista de correo es» php-install@lists.php.net.
Si quiere obtener ayuda de la lista de correo, por favor trate de ser preciso y dar toda la información necesaria a cerca de su entorno (sistema operativo, versión de PHP, servidor web, si está usando PHP como GCI o como módulo de servidor, etc.), y preferiblemente suficiente código para que otras personas sean capaces de reproducir y probar su problema.
Si cree que ha encontrado un error en PHP, por favor informe sobre él. Los desarrolladores de PHP probablemente no estén informados del problema y, a no ser que lo mencione, es muy probable que no sea solucionado. Puede informar sobre errores empleando el sistema de seguimiento de errores en» https://github.com/php/php-src/issues. Por favor, no envíe informes de errores a listas de correos o cartas personales. El sistema de errores también está capacitado para enviar sugerencias y peticiones.
Lea el documento» Cómo informar sobre erroresantes de enviar cualquier informe de errores.
El fichero de configuración (php.ini) es leído al arrancar PHP. En las versiones en que PHP funciona como módulo de servidor, esto sucede únicamente cuando se inicia el servidor. En las versionesCGIyCLI, esto ocurre en cada ejecución.
El ficherophp.inise busca en las siguientes ubicaciones (en orden):
PHPIniDiren Apache 2, opción de línea de comandos-cen CGI y CLI, parámetrophp_inien NSAPI, variable de entornoPHP_INI_PATHen THTTPD)php.inipara diferentes versiones de PHP. Se examinan en orden las siguientes claves de registro:[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z],[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]y[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], donde 'x', 'y' y 'z' significan la versión mayor, menor, y de edición de PHP. Si existiera un valor paraIniFilePathen cualquiera de estas claves, la primera en ser encontrada se utilizaría como ubicación del ficherophp.ini(solo en Windows).[HKEY_LOCAL_MACHINE\SOFTWARE\PHP], valor deIniFilePath(solo en Windows).--with-config-file-path.Si existiera el ficherophp-SAPI.ini(donde SAPI es la SAPI en uso, por ejemplo,php-cli.iniophp-apache.ini), se usaría éste en lugar dephp.ini. Se puede determinar el nombre de la SAPI usandophp_sapi_name().
Nota:
El servidor web Apache cambia el directorio al raíz al arrancar, haciendo que PHP intente leerphp.inidesde el sistema de ficheros raíz si existiera.
Las variables de entorno se pueden usar enphp.inicomo se muestra abajo.
Ejemplo #1 Variables de entorno dephp.ini
; PHP_MEMORY_LIMIT se toma del entorno
memory_limit = ${PHP_MEMORY_LIMIT}Las directivas dephp.inimanejadas por extensiones están documentadas en la propia página de cada extensión. Hay unalista de directivas del núcleodisponible en el apéndice. Es posible que no todas las directivas de PHP estén documentadas en el manual: para consultar una lista completa de las directivas disponibles en su versión de PHP, por favor, lea los comentarios del ficherophp.ini. Adicionalmente, puede encontrar útil» el últimophp.inidesde Git.
Ejemplo #2 Ejemplo dephp.ini
; todo texto en una línea tras un punto y coma sin comillas (;) será ignorado [php] ; los marcadores de sección (textos entre corchetes) también se ignoran ; Los valores de tipo boolean puede establecerse a: ; true, on, yes ; o false, off, no, none register_globals = off track_errors = yes ; se pueden encerrar los strings entre comillas dobles include_path = ".:/usr/local/lib/php" ; las barras invertidas reciben el mismo tratamiento que el resto de caracteres include_path = ".;c:\php\lib"
A partir de PHP 5.1.0, es posible hacer referencia a variables .ini ya existentes desde el propio fichero .ini. Ejemplo:open_basedir = ${open_basedir} ":/new/dir".
Es posible configurar PHP para que busque ficheros .ini en un directorio después de leerphp.ini. Esto se puede realizar durante la compilación estableciento la opción--with-config-file-scan-dir. En PHP 5.2.0 y posteriores, el directorio de búsqueda puede ser sobrescrito durante la ejecución estableciendo la vairable de entornoPHP_INI_SCAN_DIR.
Es posible buscar en varios directorios separándolos con el separador de rutas específico de cada plataforma (;en Windows, NetWare y RISC OS;:en las demás plataformas; el valor que PHP emplea está disponible como la constantePATH_SEPARATOR). Si se proporciona aPHP_INI_SCAN_DIRun directorio en blanco, PHP también buscará en el directorio dado durante la compilación mediante--with-config-file-scan-dir.
PHP buscará dentro de cada directorio todos los ficheros que finalicen en.inien orden alfabético. Se puede obtener una lista de los ficheros cargados, y en qué orden, llamando aphp_ini_scanned_files(), o ejecutando PHP con la opción--ini.
Se asumen que PHP está configurado con --with-config-file-scan-dir=/etc/php.d, y que el separador de rutas es :... $ php PHP cargará todos los ficheros de /etc/php.d/*.ini como ficheros de configuración. $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini como ficheros de configuración. $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php PHP cargará todos los ficheros de /etc/php.d/*.ini, y luego de /usr/local/etc/php.d/*.ini como ficheros de configuración. $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini, y luego de /etc/php.d/*.ini como ficheros de configuración.
| Versión | Descripción |
|---|---|
| 7.0.0 | Las almohadillas (#) ya no se reconocen como comentarios. |
| 5.3.0 | Las almohadillas (#) ya no deberían utilizarse como comentarios, ya que lanzarán una advertencia de obsolescencia si se emplean. |
| 5.2.0 | La variable de entornoPHP_INI_SCAN_DIRse puede establecer para sobrescribir el directorio de búsqueda mediante el script de configuración. |
| 5.1.0 | Es posible referirse a variables .ini existentes dentrode ficheros .ini. |
A partir de PHP 5.3.0 se incluye soporte para ficheros de configuración INI a nivel de directorios. Estos ficherossololos procesa la SAPI CGI/FastCGI. Esta funcionalidad deja obsoleta la extensión PECL htscanner. Si está usando Apache, use los ficheros.htaccesspara lograr el mismo efecto.
Además del ficherophp.iniprincipal, PHP explora cada directorio en busca de ficheros INI, empezando por el directorio del fichero PHP solicitado, y continuando hasta el directorio raíz de documentos (tal y como esté establecido en$_SERVER['DOCUMENT_ROOT']). En el caso de que el fichero PHP se encuentre fuera del directorio raíz de documentos, sólo se explorará su directorio.
En los ficheros INI estilo .user.ini sólo se reconocerán las configuraciones INI que tengan los modosPHP_INI_PERDIRyPHP_INI_USER.
Las dos nuevas directivas INI,user_ini.filenameyuser_ini.cache_ttlcontrolan el uso de los ficheros INI de usuarios.
user_ini.filenameestablece el nombre del fichero que PHP buscará en cada directorio; si se establece un string vacío, PHP no realizará ninguna búsqueda. El nombre por omisión es.user.ini.
user_ini.cache_ttlcontrola con qué frecuencia se releen los ficheros INI de usuario. El valor por omisión es 300 segundos (5 minutos).
Estos modos determinan cuándo y dónde se debe o no asignar una directiva de PHP, y cada directiva del manual hace referencia a uno de estos modos. Por ejemplo, algunos ajustes pueden establecerse en scripts de PHP usandoini_set(), mientras que otros requieren hacerlo enphp.inio enhttpd.conf.
Por ejemplo, el ajusteoutput_bufferingesPHP_INI_PERDIRpor tanto no puede establecerse usandoini_set(). Sin embargo, la directivadisplay_errorsesPHP_INI_ALLpor tanto se puede establecer en cualquier lugar, incluso conini_set().
| Modo | Significado |
|---|---|
PHP_INI_USER | La entrada se puede establecer en scripts de usuario (como conini_set()) o en elregistro de Windows. Desde PHP 5.3, la entrada puede ser establecida en.user.ini |
PHP_INI_PERDIR | La entrada se puede establecer enphp.ini,.htaccess,httpd.confo.user.ini(desde PHP 5.3) |
PHP_INI_SYSTEM | La entrada se puede establecer enphp.inio enhttpd.conf |
PHP_INI_ALL | La entrada se puede establecer en cualquier lugar |
Cuando se usa PHP como un módulo de Apache, se pueden cambiar los ajustes de configuración usando directivas en los ficheros de configuración de Apache (p.ej.httpd.conf) y en los ficheros.htaccess. Se necesitarán los privilegios "AllowOverride Options" o "AllowOverride All" para poder hacerlo.
Existen varias directivas de Apache que permiten cambiar la configuración de PHP desde los propios ficheros de configuración de Apache. Para un listado las directivas que sonPHP_INI_ALL,PHP_INI_PERDIR, oPHP_INI_SYSTEM, consulte el apéndice de laLista de directivas de php.ini.
php_valuenombrevalorEstablece el valor de la directiva especificada. Sólo puede usarse con las directivas de tipoPHP_INI_ALLyPHP_INI_PERDIR. Para borrar un valor previamente establecido, usenonecomo valor.
Nota:No use
php_valuepara establecer valores boolean. Debe usarse en su lugarphp_flag(ver más abajo).
php_flagnombreon|offUsado para establecer una directiva de configuración de tipo boolean. Sólo puede usarse con las directivas de tipoPHP_INI_ALLyPHP_INI_PERDIR.
php_admin_valuenombrevalorEstablece el valor de la directiva especificada. Estono se puede usaren ficheros.htaccess. Ninguna directiva establecida conphp_admin_valuepodrá ser sobrescrita por.htaccesso porini_set(). Para borrar un valor establecido previamente usenonecomo valor.
php_admin_flagnombreon|offUsado para establecer una directiva de configuración de tipo boolean. Estono se puede usaren ficheros.htaccess. Ninguna directiva establecida conphp_admin_flagpodrá ser sobrescrita por.htaccesso porini_set().
Ejemplo #1 Ejemplo de configuración de Apache
<IfModule mod_php5.c> php_value include_path ".:/usr/local/lib/php" php_admin_flag engine on </IfModule> <IfModule mod_php4.c> php_value include_path ".:/usr/local/lib/php" php_admin_flag engine on </IfModule>
Las constantes de PHP no existen fuera de PHP. Por ejemplo, enhttpd.confno se pueden usar constantes de PHP tales comoE_ALLoE_NOTICEpara establecer la directivaerror_reportingpuesto que no tendrán ningún significado y se evaluarán como0. Use en su lugar la máscara de bits asociada. Estas constantes sí pueden ser usadas enphp.ini
Cuando se ejecuta PHP en Windows, se pueden modificar los valores de configuración a nivel de directorio usando el registro de Windows. Los valores de configuración se almacenan en la clave de registroHKLM\SOFTWARE\PHP\Per Directory Values, en las subclaves correspondientes a los nombres de ruta. Por ejemplo, los valores de configuración para el directorioc:\inetpub\wwwrootse almacenarían en la claveHKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot. Los ajustes para el directorio estarán activos para cualquier script dentro de este directorio o en cualquiera de sus subdirectorios. Los valores bajo esta clave deberían tener el nombre de la directiva de configuración de PHP y el valor como string. Las constantes de PHP usadas como valor no serán procesadas. En cualquier caso, únicamente los valores de configuración modificables dePHP_INI_USERpodrán establecerse con este método, mientras que los valores dePHP_INI_PERDIRno.
Independientemente de cómo ejecute PHP, se pueden cambiar determinados valores de los scripts en tiempo de ejecución medianteini_set(). Consulte la documentación de la páginaini_set()para más información.
Si está interesado en una lista completa de los ajustes de configuración en su sistema con sus valores actuales, puede ejecutar la funciónphpinfo(), y consultar la página mostrada. Puede también acceder a los valores de directivas de configuración concretas usandoini_get()oget_cfg_var().
Cualquier cosa fuera de un par de etiquetas de apertura y cierre es ignorado por el intérprete de PHP, lo que permite que los ficheros de PHP tengan contenido mixto. Esto hace que PHP pueda ser embebido en documentos HTML para, por ejemplo, crear plantillas.
<p>Esto va a ser ignorado por PHP y mostrado por el navegador.</p>
<?phpecho'Mientras que esto va a ser interpretado.';?>
<p>Esto también será ignorado por PHP y mostrado por el navegador.</p>Empleo de estructuras con condiciones
Ejemplo #1 Salida avanzada usando condiciones
<?phpif ($expresión==true):?>
Esto se mostrará si la expresión es verdadera.
<?phpelse:?>
En caso contrario se mostrará esto.
<?phpendif;?>Para imprimir bloques de texto grandes, es más eficiente abandonar el modo intérprete de PHP que enviar todo el texto a través deechooprint.
En PHP 5 existen hasta cinco pares de etiquetas de apertura y cierre diferentes, dependiendo de la configuración de PHP. Dos de estas,<?php ?>y<script language="php"> </script>, siempre están disponibles. También existe una etiqueta echo abreviada,<?= ?>, que siempre está disponible en PHP 5.4.0 y posteriores.
Las otras dos son las etiquetas abreviadas y las etiquetas al estilo deASP. De por sí, aunque algunos encuentran prácticas, las etiquetas abreviadas y las etiquetas al estiloASPson menos portables, no recomendándose por lo general.
Nota:
Observe también que si se está embebiendo PHP dentro de XML o XHTML será necesario usar las etiquetas <?php ?> para seguir los estándares.
PHP 7 elimina el soprte para las etiquetasASPy<script language="php">. Por tanto, para maximizar la compatibilidad, se recomienda solamente el empleo de<?php ?>y<?= ?>al escribir código de PHP.
Ejemplo #2 Etiquetas de apertura y de cierre de PHP
1.<?phpecho'si quiere proveer código de PHP a documentos XHTML o XML,
emplee estas etiquetas';?>
2. Puede emplear la etiqueta echo abreviada para<?='imprimir esta cadena'?>.
Siempre está habilitada en PHP 5.4.0 y posterior, y es equivalente a
<?phpecho'imprimir esta cadena'?>.
3. <? echo 'este código está dentro de etiquetas abreviadas, aunque sólo '.
'funcionará si short_open_tag está habilitada'; ?>
4. <script language="php">
echo 'a algunos editores (como FrontPage) no les gustan
las instruciones de procesamiento dentro de estas etiquetas';
</script>
Esta sintaxis ha sido eliminada en PHP 7.0.0.
5. <% echo 'Opcionalmente, se pueden emplear las etiquetas al estilo de ASP'; %>
El código dentro de estas etiquetas <%= $variable; %> es una abreviatura para este código <% echo $variable; %>
Ambas sintaxis han sido eliminadas en PHP 7.0.0.Las etiquetas abreviadas (ejemplo tres) solamente están disponibles cuando se activan mediante la directivashort_open_tagdel fichero de configuraciónphp.inio si PHP se configuró con la opción--enable-short-tags.
Las etiquetas de estilo deASP(ejemplo cinco) solamente están disponibles cuando se activan mediante la directivaasp_tagsdel fichero de configuraciónphp.ini. Han sido eliminadas en PHP 7.0.0.
Nota:
Debe evitarse el uso de etiquetas abreviadas cuando se desarrollen aplicaciones o bibliotecas que estén pensadas para su redistribución o despliegue en servidores de PHP que no estén bajo su control, porque puede que las etiquetas abreviadas no estén admitidas en un servidor determinado. Por portabilidad y código redistribuible, asegúrese de no usar etiquetas abreviadas.
Nota:
En PHP 5.2 y anteriores, el analizador no permite que un fichero contenga únicamente la etiqueta de apertura
<?php. A partir de PHP 5.3 sí se permite, siempre que existan uno o más caracteres espacio en blanco después de la etiqueta de apertura.
Nota:
Desde PHP 5.4, la etiqueta de echo abreviada
<?=siempre es aceptada y válida, independientemente de la configuración deshort_open_tag.
Como en C o en Perl, PHP requiere que las instrucciones terminen en punto y coma al final de cada sentencia. La etiqueta de cierre de un bloque de código de PHP automáticamente implica un punto y coma; no es necesario usar un punto y coma para cerrar la última línea de un bloque de PHP. La etiqueta de cierre del bloque incluirá la nueva línea final inmediata si está presente.
<?php
echo'Esto es una prueba';
?>
<?phpecho'Esto es una prueba'?>
<?phpecho'Hemos omitido la última etiqueta de cierre';Nota:
La etiqueta de cierre de un bloque de PHP es opcional al final de un fichero, y en algunos casos es útil omitirla cuando se usaincludeorequire, para que no se produzcan espacios en blanco al final de los ficheros, pudiéndose aún añadir así cabeceras para la respuesta posterior. También es práctico si se utiliza la salida del buffer y no se desean espacios en blanco no deseados al final de las partes generadas por ficheros incluídos.
PHP admite comentarios al estilo de 'C', 'C++' y de consola de Unix (estilo de Perl). Por ejemplo:
<?php
echo'Esto es una prueba';// Esto es un comentario al estilo de c++ de una sola línea
/* Esto es un comentario multilínea
y otra lína de comentarios */
echo'Esto es otra prueba';
echo'Una prueba final';# Esto es un comentario al estilo de consola de una sola línea
?>Los comentarios al estilo de "una sola línea" solo comentan hasta el final de la línea o del bloque actual de código de PHP, lo primero que suceda. Esto implica que el código HTML después de// ... ?>o# ... ?>SERÁ impreso: ?> sale del modo PHP y vuelve al modo HTML, por lo que//o#no pueden influir en eso. Si la directiva de configuraciónasp_tagsestá activada, actúa igual que// %>y# %>. Sin embargo, la etiqueta</script>no sale del modo PHP en un comentario de una sola línea.
<h1>Esto es un<?php# echo 'simple';?>ejemplo</h1>
<p>El encabezado anterior dirá 'Esto es un ejemplo'.</p>Los comentarios al estilo de 'C' finalizan con el primer*/que se encuentre. Asegúrese de no anidar comentarios al estilo de 'C'. Es muy fácil cometer este error cuando se intenta comentar un bloque grande de código.
<?php
/*
echo 'Esto es una prueba'; /* Este comentario causará un problema*/
*/
?>PHP admite diez tipos primitivos.
Cuatro tipos escalares:
Cuatro tipos compuestos:
Y finalmente dos tipos especiales:
Puede que existan aún algunas referencias al tipo "double" en el manual. Considere al tipo double como float; los dos nombres existen sólo por razones históricas.
El tipo de una variable usualmente no lo declara el programador; al contrario, es decidido en tiempo de ejecución por PHP dependiendo del contexto en el que se emplea dicha variable.
Nota:Para comprobar el tipo y el valor de unaexpresión, utilice la funciónvar_dump().
Para obtener una representación legible por humanos de un tipo con propósitos de depuración, use la funcióngettype(). Para comprobar un cierto tipo,noempleegettype(), si no las funciones
is_tipo. Algunos ejemplos:<?php
$un_bool=TRUE;// un valor booleano
$un_str="foo";// una cadena de caracteres
$un_str2='foo';// una cadena de caracteres
$un_int=12;// un número entero
echogettype($un_bool);// imprime: boolean
echogettype($un_str);// imprime: string
// Si este valor es un entero, incrementarlo en cuatro
if (is_int($un_int)) {
$un_int+=4;
}
// Si $un_bool es una cadena, imprimirla
// (no imprime nada)
if (is_string($un_bool)) {
echo"Cadena:$un_bool";
}
?>
Para forzar la conversión de una variable a un cierto tipo, puedeamoldarla variable o usar la funciónsettype()con ella.
Observe que una variable puede ser evaluada con valores diferentes en ciertas situaciones, dependiendo del tipo que posea en cada momento. Para más información, lea la sección sobreManipulación de tipos.Las tablas de comparación de tipospueden resultar útiles también, ya que muestran ejemplos de varias comparaciones relacionadas con tipos.
Este es el tipo más simple. Unbooleanexpresa un valor que indica verdad. Puede sertrue(verdadero) ofalse(falso).
Para especificar un literal de tipobooleanse emplean las constantestrueofalse. Ambas no son susceptibles a mayúsculas y minúsculas.
<?php
$foo=True;// asigna el valor TRUE a $foo
?>Usualmente, el resultado de unoperadorque devuelve un valor de tipobooleanes pasado a unaestructura de control.
<?php
// == es un operador que comprueba la
// igualdad y devuelve un booleano
if ($accion=="mostrar_version") {
echo"La versión es 1.23";
}
// esto no es necesario...
if ($mostrar_separadores==TRUE) {
echo"<hr>\n";
}
// ...porque se puede escribir simplemente:
if ($mostrar_separadores) {
echo"<hr>\n";
}
?>Para convertir explícitamente un valor al tipoboolean, use los amoldamientos(bool)o(boolean). Sin embargo, en la mayoría de casos es innecesario el amoldamiento, ya que un valor será convertido automáticamente si un operador, función o estructura de control requiere un argumento de tipoboolean.
Véase también laManipulación de tipos.
Cuando se realizan conversiones aboolean, los siguientes valores se consideranfalse:
falsemismoCualquier otro valor se considera comotrue(incluido cualquierresourceyNAN).
-1se consideratrue, como cualquier otro número distinto de cero (ya sea negativo o positivo).
<?php
var_dump((bool)"");// bool(false)
var_dump((bool)1);// bool(true)
var_dump((bool) -2);// bool(true)
var_dump((bool)"foo");// bool(true)
var_dump((bool)2.3e5);// bool(true)
var_dump((bool) array(12));// bool(true)
var_dump((bool) array());// bool(false)
var_dump((bool)"false");// bool(true)
?>Un número entero (ointeger) es un número del conjunto ℤ = {..., -2, -1, 0, 1, 2, ...}.
Véase también:
Losintegerpueden especificarse mediante notación decimal (base 10), hexadecimal (base 16), octal (base 8) o binaria (base 2), opcionalmente precedidos por un signo (- o +).
Los literales de tipointegerbinarios están disponibles desde PHP 5.4.0.
Para utilizar la notación octal, se antepone al número un0(cero). Para utilizar la notación hexadecimal, se antepone al número0x. Para utilizar la notación binaria, se antepone al número0b.
Ejemplo #1 Literales de números enteros
<?php
$a=1234;// número decimal
$a= -123;// un número negativo
$a=0123;// número octal (equivale a 83 decimal)
$a=0x1A;// número hexadecimal (equivale a 26 decimal)
$a=0b11111111;// número binario (equivale al 255 decimal)
?>Formalmente, la estructura de los literales de tipointegeres:
decimal : [1-9][0-9]*
| 0
hexadecimal : 0[xX][0-9a-fA-F]+
octal : 0[0-7]+
binario : 0b[01]+
entero : [+-]?decimal
| [+-]?hexadecimal
| [+-]?octal
| [+-]?binario
El tamaño de unintegerdepende de la plataforma, aunque el valor usual es un valor máximo de aproximadamente dos mil millones (esto es, 32 bits con signo). Las plataformas de 64 bits normalmente tienen un valor máximo de aproximadamente 9E18, excepto en Windows antes de PHP 7, que siempre es de 32 bits. PHP no tiene soporte para el tipointegersin signo. El tamaño de unintegerse puede determinar mediante la constantePHP_INT_SIZE, y el valor máximo mediante la constantePHP_INT_MAXdesde PHP 4.4.0 y PHP 5.0.5, y el valor mínimo mediante la constantePHP_INT_MINdesde PHP 7.0.0.
Antes de PHP 7, si a unintegeroctal se le proporcionaba un dígito no válido (esto es, 8 o 9), se ignoraba el resto del número. Desde PHP 7, se emite un error de análisis.
Si PHP encuentra un número fuera de los límites de uninteger, se interpretará en su lugar como un valor de tipofloat. También, una operación cuyo resultado sea un número fuera de los límites de unintegerdevolverá en su lugar un valor de tipofloat.
Ejemplo #2 Desbordamiento de enteros en sistemas de 32 bit
<?php
$número_grande=2147483647;
var_dump($número_grande);// int(2147483647)
$número_grande=2147483648;
var_dump($número_grande);// float(2147483648)
$millón=1000000;
$número_grande=50000*$millón;
var_dump($número_grande);// float(50000000000)
?>Ejemplo #3 Desbordamiento de enteros en sistemas de 64 bit
<?php
$número_grande=9223372036854775807;
var_dump($número_grande);// int(9223372036854775807)
$número_grande=9223372036854775808;
var_dump($número_grande);// float(9.2233720368548E+18)
$millón=1000000;
$número_grande=50000000000000*$millón;
var_dump($número_grande);// float(5.0E+19)
?>No existe el operador de división deintegeren PHP.1/2produce elfloat0.5. El valor puede ser convertido a unintegerredondeándolo a cero, o mediante la funciónround()que permite un mayor control sobre el redondeo.
<?php
var_dump(25/7);// float(3.5714285714286)
var_dump((int) (25/7));// int(3)
var_dump(round(25/7));// float(4)
?>Para convertir explícitamente un valor al tipointegerse puede emplear tanto(int)como(integer). Sin embargo, la mayoría de las veces la conversión no es necesaria, ya que un valor es convertido de forma automática cuando un operador, función o estructura de control requiera un argumento de tipointeger. Un valor también puede ser convertido al tipointegermediante la funciónintval().
Si unresourcees convertido a uninteger, el resultado será el número de recurso único asignado alresourcepor PHP durante la ejecución.
Consulte también laManipulación de tipos.
falseproducirá0(cero), ytrueproducirá1(uno).
Cuando se convierte unfloata uninteger, el número será redondeadohacia cero.
Si el valor de tipo float esta por debajo de los límites de uninteger(normalmente+/- 2.15e+9 = 2^31en plataformas de 32 bits y+/- 9.22e+18 = 2^63en plataformas de 64 bits distintas de Windows), el resultado es indefinido, debido a quefloatno tiene la precisión suficiente para ofrecer el resultado como unintegerexacto. No se mostrará ninguna advertencia, ni siquiera un aviso, cuando esto ocurra.
Nota:
A partir de PHP 7.0.0,0, en lugar de ser indefinidos y dependientes de la plataforma, NaN e Infinity siempre serán cero al amoldarlos ainteger.
Nunca se debe convertir una fracción desconocida a uninteger, ya que a veces puede conducir a resultados inesperados.
<?php
echo (int) ( (0.1+0.7) *10);// ¡muestra 7!
?>Consulte también laadvertencia sobre la precisión de float
ConsulteConversión de string a números
El comportamiento de la conversión deintegera otros tipos es indefinido.Noconfíe en ningún comportamiento observado, ya que puede cambiar sin previo aviso.
Los números de punto flotante (también conocidos como "de coma flotante" en español, y "floats" en inglés) pueden ser especificados usando cualquiera de las siguientes sintaxis:
<?php
$a=1.234;
$b=1.2e3;
$c=7E-10;
$d=1_234.567;// a partir de PHP 7.4.0
?>Formalmente a partir de PHP 7.4.0 (anteriormente, no se permitían los guiones bajos):
LNUM [0-9]+(_[0-9]+)*
DNUM ([0-9]*(_[0-9]+)*[\.]{LNUM}) | ({LNUM}[\.][0-9]*(_[0-9]+)*)
EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
El tamaño de un 'float' depende de la plataforma, aunque un valor común consiste en un máximo de aproximadamente 1.8e308 con una precisión cercana a los 14 dígitos decimales (el formato de 64 bit del IEEE).
Los números de punto flotante tienen una precisión limitada. Aunque depende del sistema, PHP típicamente utiliza el formato de doble precisión IEEE 754, el cual dará un error relativo máximo por aproximación del orden de 1.11e-16. Las operaciones aritméticas elementales no podrán generar grandes errores y, por supuesto, se han de considrar los errores por propagación al componer varias operaciones.
Adicionalmente, los numeros racionales que son representables exactamente como números de punto flotante en base 10, como0.1o0.7, no tienen una representación exacta como números de punto flotante en base 2, que es la base empleada internamente, sin importar el tamaño de la mantisa. Por lo tanto, no se pueden convertir en sus equivalentes binarios internos sin una pequeña pérdida de precisión. Esto puede conducir a resultados confusos: Por ejemplo,floor((0.1+0.7)*10)usualmente devolverá7en lugar del8previsto, ya que la representación interna será algo así como7.9999999999999991118....
Por tanto, nunca se ha de confiar en resultados de números flotantes hasta el último dígito, y no comparar la igualdad de números de punto flotante directamente. Si fuera necesaria una mayor precisión, están disponibles lasfunciones matemáticas de precisión arbitrariay las funciones degmp.
Para una explicación "simple", véase la» guía del punto flotanteque también se titula "¿Por qué no sale la cuenta?"
Para más información sobre las conversiones destringafloat, véase laConversión de cadenas a números. Para valores de otros tipos, la conversión es la misma que si el valor hubiese sido convertido primero aintegery luego afloat. Véase laConversión a al tipo integerpara más información. A partir de PHP 5, se genera un aviso si se intenta convertir unobjectafloat.
Como se indica en la advertencia anterior, comprobar la igualdad de valores de punto flotante es problemático debido a la forma en que se representan internamente. Sin embargo, hay maneras de hacer comparaciones de los valores de punto flotante que evitan estas limitaciones.
Para comprobar la igualdad de valores de punto flotante, se utiliza un límite superior en el error relativo debido al redondeo. Este valor se conoce como el épsilon de la máquina o unidad de redondeo, y es la menor diferencia aceptable en los cálculos.
$ay$bson iguales en 5 dígitos de precisión.
<?php
$a=1.23456789;
$b=1.23456780;
$épsilon=0.00001;
if(abs($a-$b) <$épsilon) {
echo"true";
}
?>Algunas operaciones numéricas pueden resultar en un valor representado por la constanteNAN. Este resultado representa un valor no definido o no representable mediante cálculos de punto flotante. Cualquier comparación, ya sea estricta o no, de este valor con cualquier otro valor, incluido él mismo, pero exceptotrue, tendrá un resultado defalse.
Ya queNANrepresenta cualquier número de diferentes valores,NANno debería compararse con otros valores, incluido él mismo; en su lugar debería comprobarse usando la funciónis_nan().
Unstring, o cadena, es una serie de caracteres donde cada carácter es lo mismo que un byte. Esto significa que PHP solo admite un conjunto de 256 caracteres, y de ahí que no ofrezca soporte nativo para Unicode. Véanse losdetalles del tipo string.
Nota:Unstringpuede llegar a alcanzar hasta 2 GB de tamaño (2147483647 bytes máximo).
Un literal de tipostringse puede especificar de cuatro formas diferentes:
La manera más sencilla de especificar unstringes delimitarlo con comillas simples (el carácter').
Para especificar una comilla simple literal, se ha de escapar con una barra invertida (\). Para especificar una barra invertida literal, se duplica (\\). Todas las demás instancias de barras invertidas serán tratadas como una barra invertida literal: esto significa que otras secuencias de escape que podrían utilizarse, tales como\ro\n, serán mostradas literalmente tal y como se especifican, en lugar de tener cualquier otro significado especial.
Nota:A diferencia de las sintaxis deentrecomillado dobleyheredoc, lasvariablesy las sentencias de escape para caracteres especialesnose expandirán cuando estén incluidas dentro de unstringentre comillas simples.
<?php
echo'Esto es una cadena sencilla';
echo'También se pueden incluir nuevas líneas en
un string de esta forma, ya que es
correcto hacerlo así';
// Resultado: Arnold una vez dijo: "I'll be back"
echo'Arnold una vez dijo: "I\'ll be back"';
// Resultado: Ha borrado C:\*.*?
echo'Ha borrado C:\\*.*?';
// Resultado: Ha borrado C:\*.*?
echo'Ha borrado C:\*.*?';
// Resultado: Esto no se expandirá: \n una nueva línea
echo'Esto no se expandirá: \n una nueva línea';
// Resultado: Las variables $tampoco se $expandirán
echo'Las variables $tampoco se $expandirán';
?>Si unstringestá delimitado con comillas dobles ("), PHP interpretará las siguientes secuencias de escape como caracteres especiales:
| Secuencia | Significado |
|---|---|
\n | avance de línea (LF o 0x0A (10) en ASCII) |
\r | retorno de carro (CR o 0x0D (13) en ASCII) |
\t | tabulador horizontal (HT o 0x09 (9) en ASCII) |
\v | tabulador vertical (VT o 0x0B (11) en ASCII) (desde PHP 5.2.5) |
\e | escape (ESC o 0x1B (27) en ASCII) (desde PHP 5.4.4) |
\f | avance de página (FF o 0x0C (12) en ASCII) (desde PHP 5.2.5) |
\\ | barra invertida |
\$ | signo de dólar |
\" | comillas dobles |
\[0-7]{1,3} | la secuencia de caracteres que coincida con la expresión regular es un carácter en notación octal, que silenciosamente desborda para encajar en un byte (p.ej. "\400" === "\000") |
\x[0-9A-Fa-f]{1,2} | la secuencia de caracteres que coincida con la expresión regular es un carácter en notación hexadecimal |
\u{[0-9A-Fa-f]+} | la secuencia de caracteres que coincida con la expresión regular es un punto de código de Unicode, la cual será imprimida al string como dicha representación UTF-8 del punto de código (añadido en PHP 7.0.0) |
Al igual que en el entrecomillado simple de unstring, escapar cualquier otro carácter puede dar lugar a que se muestre también la barra invertida. Antes de PHP 5.1.1, no se mostraba la barra invertida de\{$var}.
La característica más importante del entrecomillado doble de unstringes el hecho de que se expanden los nombres de las variables. Consulte elanálisis de stringpara más detalles.
Una tercera forma de delimitar unstringes mediante la sintaxis heredoc:<<<. Después de este operador, se deberá proporcionar un identificador y justo después una nueva línea. A continuación va el propiostring, y para cerrar la notación se pone el mismo identificador.
El identificador de cierredebeempezar en la primera columna de la nueva línea. Asimismo, el identificador debe seguir las mismas reglas de nomenclatura de las etiquetas en PHP: debe contener solo caracteres alfanuméricos y guiones bajos, y debe empezar con un carácter alfabético o un guión bajo.
Es muy importante señalar que la línea con el identificador de cierre no debe contener ningún otro carácter, excepto un punto y coma (;). Esto, en especial, significa que el identificadorno debe estar sangrado, y que no debe existir ningún espacio ni tabulación antes o después del punto y coma. Es muy importante observar que el primer carácter antes del identificador de cierre debe ser un salto de línea definido por el sistema operativo local. Este es\nen los sistemas UNIX, incluyendo Mac OS X. Al delimitador de cierre le ha de seguir tambíen una nueva línea.
Si se rompe esta regla y el identificador de cierre no está "limpio", no será considerado como un identificador de cierre, por lo que PHP continuará buscando uno. Si no se encuentra ningún identificador de cierre apropiado antes del final del fichero, se producirá un error de análisis en la última línea.
No se puede emplear Heredoc para inicializar las propiedades de una clase. Desde PHP 5.3, esta limitación es válida solamente para un heredoc que contengan variables.
Ejemplo #1 Ejemplo no válido
<?php
classfoo{
public$bar= <<<EOT
bar
EOT;
}
?>El texto heredoc se comporta como unstringentre comillas dobles, pero sin tener comillas dobles. Esto significa que no es necesario escapar las comillas en un heredoc, aunque se puede seguir empleando los códigos de escape indicados arriba. Pese a que las variables son expandidas, se debe tener el mismo cuidado al expresar variables complejas en un heredoc que en unstring.
Ejemplo #2 Ejemplo de entrecomillado de string en Heredoc
<?php
$str= <<<EOD
Ejemplo de una cadena
expandida en varias líneas
empleando la sintaxis heredoc.
EOD;
/* Un ejemplo más complejo con variables. */
classfoo
{
var$foo;
var$bar;
functionfoo()
{
$this->foo='Foo';
$this->bar= array('Bar1','Bar2','Bar3');
}
}
$foo= newfoo();
$nombre='MiNombre';
echo <<<EOT
Mi nombre es "$nombre". Estoy escribiendo un poco de$foo->foo.
Ahora, estoy escribiendo un poco de{$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41
EOT;
?>El resultado del ejemplo sería:
Mi nombre es "MiNombre". Estoy escribiendo un poco de Foo. Ahora, estoy escribiendo un poco de Bar2. Esto debería mostrar una 'A' mayúscula: A
También se puede emplear la sintaxis Heredoc para pasar datos como argumentos de una función:
Ejemplo #3 Ejemplo de Heredoc en argumentos
<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>Desde PHP 5.3.0, es posible inicializar variables estáticas y propiedades/constantes de clase mediante la sintaxis Heredoc:
Ejemplo #4 Usar Heredoc para inicializar valores estáticos
<?php
// Variables estáticas
functionfoo()
{
static$bar= <<<LABEL
Nada aquí...
LABEL;
}
// Propiedades/constantes de clase
classfoo
{
constBAR= <<<FOOBAR
Ejemplo de constante
FOOBAR;
public$baz= <<<FOOBAR
Ejemplo de propiedad
FOOBAR;
}
?>PHP 5.3.0 también introdujo la posibilidad de entrecomillar el identificador de apertura en Heredoc:
Ejemplo #5 Emplear comillas dobles en Heredoc
<?php
echo <<<"FOOBAR"
¡Hola Mundo!
FOOBAR;
?>Nowdoc es a los string con comillas simples lo mismo que Heredoc lo es a los string con comillas dobles. Un nowdoc se especifica de forma análoga a un heredoc, perono se realiza ningún análisisdentro del nowdoc. La construcción es ideal para embeber código de PHP o grandes fragmentos de texto sin necesidad de escaparlos. Comparte algunas características comunes con la construcción<![CDATA[ ]]>de SGML, donde se declara un bloque de texto que no se analiza.
Un nowdoc se identifica con la misma secuencia empleada para heredoc,<<<, pero el identificador que le sigue está delimitado con comillas simples, p.ej.,<<<'EOT'. Todas las reglas para los identificadores de heredoc también son aplicables a los identificadores de nowdoc, especialmente aquellas que se refieren al empleo del identificador de cierre.
Ejemplo #6 Ejemplo de entrecomillado de string de Nowdoc
<?php
$str= <<<'EOD'
Ejemplo de un string
expandido en varias líneas
empleando la sintaxis nowdoc.
EOD;
/* Un ejemplo más complejo con variables. */
classfoo
{
public$foo;
public$bar;
functionfoo()
{
$this->foo='Foo';
$this->bar= array('Bar1','Bar2','Bar3');
}
}
$foo= newfoo();
$nombre='MiNombre';
echo <<<'EOT'
Mi nombre es "$nombre". Estoy escribiendo un poco de $foo->foo.
Ahora, estoy escribiendo un poco de {$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41
EOT;
?>El resultado del ejemplo sería:
Mi nombre es "$nombre". Estoy escribiendo un poco de $foo->foo.
Ahora, estoy escribiendo un poco de {$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41Ejemplo #7 Ejemplo de datos estáticos
<?php
classfoo{
public$bar= <<<'EOT'
bar
EOT;
}
?>Nota:
El soporte para Nowdoc se añadió en PHP 5.3.0.
Cuando unstringes especificado mediante comillas dobles o mediante heredoc, lasvariablesque haya dentro de dicho string se analizarán.
Existen dos tipos de sintaxis: unasimpley otracompleja. La sintaxis simple es la más empleada y práctica. Proporciona una forma de embeber una variable, un valor de unarrayo una propiedad de unobjectdentro de unstringcon el mínimo esfuerzo.
La sintaxis compleja puede ser reconocida por las llaves que delimitan la expresión.
Si se encuentra un signo de dólar ($), el analizador tomará el mayor número de símbolos para formar un nombre de variable válido. Delimitar el nombre de la variable con llaves permite especificar explícitamente el final del nombre.
<?php
$jugo="manzana";
echo"Él tomó algo de jugo de$jugo.".PHP_EOL;
// Inválido. "s" es un carácter válido para un nombre de variable, pero la variable es $jugo.
echo"Él tomó algo de jugo hecho de$jugos.";
// Válido. Explícitamente especifica el final del nombre de la variable encerrándolo entre llaves:
echo"Él tomó algo de jugo hecho de${jugo}s."
?>El resultado del ejemplo sería:
Él tomó algo de jugo de manzana. Él tomó algo de jugo hecho de . Él tomó algo de jugo hecho de manzanas.
De forma parecida, se puede analizar el índice de unarrayo la propiedad de unobject. Con los índices de los arrays, el corchete de cierre (]) marca el final del índice. La misma regla se puede aplicar a las propiedades de los objetos y a las variables simples.
Ejemplo #8 Ejemplo de sintaxis simple
<?php
$jugos= array("manzana","naranja","koolaid1"=>"púrpura");
echo"Él tomó algo de jugo de$jugos[0].".PHP_EOL;
echo"Él tomó algo de jugo de$jugos[1].".PHP_EOL;
echo"Él tomó algo de jugo$jugos[koolaid1].".PHP_EOL;
classpersona{
public$john="John Smith";
public$jane="Jane Smith";
public$robert="Robert Paulsen";
public$smith="Smith";
}
$persona= newpersona();
echo"$persona->johntomó algo de jugo de$jugos[0].".PHP_EOL;
echo"$persona->johnentonces dijo hola a$persona->jane.".PHP_EOL;
echo"La esposa de$persona->johnsaludó a$persona->robert.".PHP_EOL;
echo"$persona->robertsaludó a los dos$persona->smiths.";// No funcionará
?>El resultado del ejemplo sería:
Él tomó algo de jugo de manzana. Él tomó algo de jugo de naranja. Él tomó algo de jugo púrpura. John Smith tomó algo de jugo de manzana. John Smith entonces dijo hola a Jane Smith. La esposa de John Smith saludó a Robert Paulsen. Robert Paulsen saludó a los dos .
Para casos más complejos se debe emplear la sintaxis compleja.
Esta sintaxis no se llama compleja porque sea compleja, sino porque permite el empleo de expresiones complejas.
Cualquier variable escalar, elemento de array o propiedad de objeto con una representación de tipostringpuede ser incluido a través de esta sintaxis. Simplemente se escribe la expresión del mismo modo en que aparecería por fuera delstring, y delimitándola con{y}. Dado que{no puede ser escapado, esta sintaxis será reconocida únicamente cuando el$siga inmediatamente al{. Utilice{\$para obtener un{$literal. Algunos ejemplos para que quede más claro:
<?php
// Mostrar todos los errores
error_reporting(E_ALL);
$genial='fantástico';
// No funciona, muestra: Esto es { fantástico}
echo"Esto es {$genial}";
// Funciona, muestra: Esto es fantástico
echo"Esto es{$genial}";
// Funciona
echo"Este cuadrado tiene{$cuadrado->width}00 centímetros de lado.";
// Funciona, las claves entre comillas sólo funcionan usando la sintaxis de llaves
echo"Esto funciona:{$arr['clave']}";
// Funciona
echo"Esto funciona:{$arr[4][3]}";
// Esto no funciona por la misma razón que $foo[bar] es incorrecto fuera de un string.
// En otras palabras, aún funcionaría, pero solamente porque PHP primero busca una
// constante llamada foo; se emitirá un error de nivel E_NOTICE
// (constante no definida).
echo"Esto está mal:{$arr[foo][3]}";
// Funciona. Cuando se usan arrays multidimensionales, emplee siempre llaves que delimiten
// a los arrays cuando se encuentre dentro de un string
echo"Esto funciona:{$arr['foo'][3]}";
// Funciona.
echo"Esto funciona: ".$arr['foo'][3];
echo"Esto también funciona:{$obj->valores[3]->nombre}";
echo"Este es el valor de la variable llamada$nombre:{${$nombre}}";
echo"Este es el valor de la variable llamada por el valor devuelto por getNombre():{${getNombre()}}";
echo"Este es el valor de la variable llamada por el valor devuelto por \$objeto->getNombre():{${$objeto->getNombre()}}";
//No funciona, muestra: Esto es el valor devuelto por getNombre(): {getNombre()}
echo"Esto es el valor devuelto por getNombre(): {getNombre()}";
?>Con esta sintaxis, también es posible acceder a las propiedades de una clase empleando variables dentro de un string.
<?php
classfoo{
var$bar='Soy bar.';
}
$foo= newfoo();
$bar='bar';
$baz= array('foo','bar','baz','quux');
echo"{$foo->$bar}\n";
echo"{$foo->{$baz[1]}}\n";
?>El resultado del ejemplo sería:
Soy bar. Soy bar.
Nota:
Las funciones, llamadas a métodos, variables de clase estáticas y constantes de clases dentro de
{$}funcionan desde PHP 5. Sin embargo, el valor accedido puede ser interpretado como el nombre de la variable en el ámbito en el que está definido el string. El empleo de simples llaves ({}) no servirá para acceder al valor devuelto por las funciones o métodos, o los valores de las constantes de clase o variables de clase estáticas.
<?php
// Mostrar todos los errores.
error_reporting(E_ALL);
classcervezas{
constrefresco='zarzaparrilla';
public static$ale='ipa';
}
$zarzaparrilla='A & W';
$ipa='Alexander Keith\'s';
// Funciona; muestra: Me gusta una A & W
echo"Me gusta una{${cervezas::refresco}}\n";
// También funciona; muestra: Me gusta una Alexander Keith's
echo"Me gusta una{${cervezas::$ale}}\n";
?>Se puede acceder y modificar los caracteres dentro de unstringespecificando el índice de base cero del carácter deseado después delstringempleando los corchetes dearray, como en$str[42]. Piense en unstringcomo unarrayde caracteres, en este caso. Las funcionessubstr()ysubstr_replace()pueden ser empleadas para extraer o reemplazar más de un carácter.
Nota:También se puede acceder a unstringutilizando llaves, como en$str{42}, con el mismo propósito.
Escribir en un índice fuera del rango rellenará el string con espacios. Los tipos que no sean integer son convertidos a integer. Los índices ilegales emiten un error de nivelE_NOTICE. Los índices negativos emiten un error de nivelE_NOTICEen la escritura, aunque se lea un string vacío. Sólo se emplea el primer carácter de un string asignado. La asignación de un string vacío asigna un byte NULL.
Internamente, los string de PHP son arrays de bytes. Por tanto, acceder o modificar un string utilizando los corchetes de array no es seguro con caracteres multibyte, dado que sólo se realiza con los string de codificaciones monobyte, como ISO-8859-1.
Ejemplo #9 Algunos ejemplos de string
<?php
// Obtener el primer carácter de un string
$str='Esto es una prueba.';
$primero=$str[0];
// Obtener el tercer carácter de un string
$tercero=$str[2];
// Obtener el último carácter de un string
$str='Esto sigue siendo una prueba.';
$último=$str[strlen($str)-1];
// Modificar el último carácter de un string
$str='Mira el mar';
$str[strlen($str)-1] ='l';
?>A partir de PHP 5.4, los índices de string tienen que ser de tipo integer o integer en forma de string, si no, se emitirá una advertencia. Anteriormente, un índice como"foo"era convertido de manera silenciosa a0.
Ejemplo #10 Diferencias entre PHP 5.3 y PHP 5.4
<?php
$str='abc';
var_dump($str['1']);
var_dump(isset($str['1']));
var_dump($str['1.0']);
var_dump(isset($str['1.0']));
var_dump($str['x']);
var_dump(isset($str['x']));
var_dump($str['1x']);
var_dump(isset($str['1x']));
?>Salida del ejemplo anterior en PHP 5.3:
string(1) "b" bool(true) string(1) "b" bool(true) string(1) "a" bool(true) string(1) "b" bool(true)
Salida del ejemplo anterior en PHP 5.4:
string(1) "b" bool(true) Warning: Illegal string offset '1.0' in /tmp/t.php on line 7 string(1) "b" bool(false) Warning: Illegal string offset 'x' in /tmp/t.php on line 9 string(1) "a" bool(false) string(1) "b" bool(false)
Nota:
El acceso a variables de otros tipos (sin incluir arrays u objetos que implementen las interfaces apropiadas) utilizando
[]o{}, silenciosamente retornanull.
Nota:
PHP 5.5 añadió soporte para acceder a caracteres dentro de literales de tipo string utilizando
[]o{}.
Losstringpueden ser concatenados empleando el operador '.' (punto). Fíjese que el operador '+' (suma)noservirá para concatenar. Consulte losoperadores de stringpara más información.
Hay una serie de funciones útiles para la manipulación destring.
Consulte lasección de funciones de stringpara funciones generales, y lasfunciones de expresiones regulares compatibles con Perlpara características avanzadas de búsqueda y sustitución.
También existenfunciones para string de URL, y funciones para encriptar/desencriptar string (mcryptymhash).
Finalmente, también existen lasfunciones para el tipo carácter.
Un valor puede convertirse a unstringempleando el molde(string)o mediante la funciónstrval(). La conversión automática astringtiene lugar en el ámbito de una expresión donde sea necesario unstring. Esto ocurre cuando se utilizan las funcionesechooprint, o cuando se compara una variable con unstring. Las secciones sobreTiposyManipulación de tiposlo aclararán. Consulte también la funciónsettype().
El valortruedel tipobooleanes convertido alstring"1". El valorfalsedel tipobooleanes convertido alstring""(el string vacío). Esto permite la conversión en ambos sentidos entre los valores de los tiposbooleanystring.
Unintegerofloates convertido a unstringque representa textualmente el número (incluyendo la parte exponencial para losfloat. Los números de punto flotante pueden ser convertidos mediante la notación exponencial (4.1E+6).
Nota:
El carácter para el punto decimal se define en el localismo del script (categoría LC_NUMERIC). Consulte la funciónsetlocale().
Losarrays siempre son convertidos alstring"Array". Debido a esto,echoyprintno pueden por sí mismos mostrar el contenido de unarray. Para ver un único elemento individualmente, utilice una construcción comoecho $arr['foo']. Vea los consejos de más abajo para mostrar el contenido completo.
Losobjecten PHP 4 siempre son convertidos alstring"Object". Para mostrar los valores de las propiedades de un objeto para su depuración, lea los párrafos siguientes. Para obtener el nombre de la clase de un objeto, emplee la funciónget_class(). A partir de PHP 5, se puede emplear el método__toStringcuando sea relevante.
Unresourcesiempre es convertido astringcon la estructura"Resource id #1", donde1es el número de recurso asignado alresourcepor PHP durante la ejecución. A pesar de que no se debe depender de la estructura exacta, debido a que está sujeta a cambios, siempre será única para un recurso dado dentro del tiempo de vida de un script en ejecución (es decir, una petición web o proceso CLI), por lo que no será reutilizada. Para obtener el tipo de unresource, emplee la funciónget_resource_type().
nullsiempre es convertido a un string vacío.
Como se indicó anteriormente, la conversión directa de unarray,objectoresourcea unstringno proporciona información útil acerca del valor más allá de su tipo. Consulte las funcionesprint_r()yvar_dump()para ver medios más efectivos de inspeccionar el contenido de estos tipos.
La mayoría de los valores de PHP pueden ser convertidos a unstringpara su almacenamiento permanente. Este método se denomina serialización, y es realizado mediante la funciónserialize(). Si el motor de PHP se construyó con soporte paraWDDX, los valores de PHP también pueden ser serializacos como texto XML bien formado.
Cuando unstringes evaluado en un contexto numérico, el valor resultante y el tipo se determina como se explica a continuación.
Si elstringno contiene ninguno de los caracteres '.', 'e', o 'E', y el valor numérico está entre los límites del tipo integer (tal como está definido porPHP_INT_MAX), elstringserá evaluado como uninteger. En todos los demás casos será evaluado como unfloat.
El valor es dado por la parte inicial delstring. Si elstringempieza con un dato numérico válido, éste será el valor empleado. De lo contrario, el valor será 0 (cero). Un dato numérico válido es un signo opcional, seguido de uno o más dígitos (opcionalmente puede contener un punto decimal), seguido de un exponente opcional. El exponente es una 'e' o 'E' seguida de uno o más dígitos.
<?php
$foo=1+"10.5";// $foo es float (11.5)
$foo=1+"-1.3e3";// $foo es float (-1299)
$foo=1+"bob-1.3e3";// $foo es integer (1)
$foo=1+"bob3";// $foo es integer (1)
$foo=1+"10 pequeños cerdos";// $foo es integer (11)
$foo=4+"10.2 pequeños cerditos";// $foo es float (14.2)
$foo="10.0 cerdos "+1;// $foo es float (11)
$foo="10.0 cerdos "+1.0;// $foo es float (11)
?>Para más información sobre esta conversión, consulte la página del manual de Unix para a strtod(3).
Para probar cualesquiera de los ejemplos de esta sección, copie y péguelos e incluya la siguiente línea para ver lo que está sucediendo:
<?php
echo"\$foo==$foo; tipo : ".gettype($foo) ."<br />\n";
?>No espere obtener el código de un carácter convirtiéndolo a un integer, como ocurre en C. Emplee las funcionesord()ychr()para convertir entre código códigos ASCII y caracteres.
En PHP, losstringse implementan como un array de bytes y con un número entero que indica la longitud del búfer. No posee ninguna información sobre cómo traducir esos bytes a caracteres, relegando esa tarea al programador. No existe ninguna limitación sobre los valores que pueden componer un string; en concreto, está permitido colocar bytes con valor0(“bytes NUL”) en cualquier posición del string (aunque existen algunas funciones, citadas en este manual como “no seguras a nivel binario”, que podrían rechazar estos string para aquellas bibliotecas que ignoren los datos que siguen a un byte NUL.)
Este comportamiento del tipo string justifica que no exista un tipo de dato "byte" en PHP – los string se encargan de esto. Las funciones que no devuelven datos de texto – por ejemplo, cualquier dato leído a partir de un socket de red – devolverán valores de tipo string.
Dado que PHP no obliga a utilizar ninguna condificación en particular, uno podría preguntarse cómo se codifican los literales de tipo string. Por ejemplo, ¿es el string"á"equivalente a"\xE1"(ISO-8859-1),"\xC3\xA1"(UTF-8, forma C),"\x61\xCC\x81"(UTF-8, forma D) o cualquier otra representación posible? La respuesta es que un string será codificado en cualquiera forma en que estuviera codificado el fichero del script. Por tanto, si un script estuviera escrito en ISO-8859-1, el string se codificará en ISO-8859-1, etc. Sin embargo, esto no es aplicable si está habilitado Zend Multibyte; en ese caso, el script podría estar escrito en cualquier codificación (la cual es declarada explícitamente o es detectada) para después convertirse a una determinada codificación interna, que será entonces la codificación usada para los literales de tipo string. Tenga presente que existen algunas limitaciones sobre la codificación del script (o en la codificación interna, si Zend Multibyte estuviera habilitado); esto suele significar que dicha codificación debería ser compatible con un superconjunto de ASCII, tal como UTF-8 o ISO-8859-1. Por contra, las codificaciones dependientes del estado donde se pueden utilizar los mismos valores de byte en estados de desplazamiento iniciales y no iniciales, podrían generar problemas.
Por supuesto, para poder ser útiles, las funciones que operen con texto podrían partir de unos supuestos sobre cómo está codificado el string. Desafortunadamente, respecto a esto existen muchas variaciones en las funciones de PHP:
strtoupper("á")podría devolver"Á"si el localismo está correctamente establecido yáestá codificado con un único byte. Si está codificado en UTF-8, no se devolverá un resultado correcto, y el string resultante podría devolverse corrupto, en función del localismo en uso.u). Debido a su propósito especial, la funciónutf8_decode()asume una codificación UTF-8, mientras que la funciónutf8_encode()asume una codificación ISO-8859-1.En resumen, para escribir programas de forma correcta usando Unicode hay que evitar cuidadosamente las funciones que puedan fallar y que muy probablemente corrompan los datos, y utilizar en su lugar las funciones que se comporten de forma correcta, generalmente las de las extensionesintlymbstring. Sin embargo, el uso de funciones que pueden manejar codificaciones Unicode es sólo el principio. No importa qué funciones incorpore el lenguaje; es primordial conocer la especificación Unicode. Por ejemplo, un programa que asuma que sólo hay mayúsculas y minúsculas estará haciendo una suposición errónea.
A PHPstringis considered numeric if it can be interpreted as anintor afloat.
Formally as of PHP 8.0.0:
WHITESPACES \s*
LNUM [0-9]+
DNUM ([0-9]*)[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
INT_NUM_STRING {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
NUM_STRING ({INT_NUM_STRING} | {FLOAT_NUM_STRING})
PHP also has a concept ofleadingnumeric strings. This is simply a string which starts like a numeric string followed by any characters.
Nota:
Any string that contains the letter
E(case insensitive) bounded by numbers will be seen as a number expressed in scientific notation. This can produce unexpected results.<?php
var_dump("0D1"=="000");// false, "0D1" is not scientific notation
var_dump("0E1"=="000");// true, "0E1" is 0 * (10 ^ 1), or 0
var_dump("2E1"=="020");// true, "2E1" is 2 * (10 ^ 1), or 20
?>
When astringneeds to be evaluated as number (e.g. arithmetic operations,inttype declaration, etc.) the following steps are taken to determine the outcome:
PHP_INT_MAX), otherwise resolve to afloat.PHP_INT_MAX), otherwise resolve to afloat. Additionally an error of levelE_WARNINGis raised.Prior to PHP 8.0.0, astringwas considered numeric only if it hadleadingwhitespaces, if it hadtrailingwhitespaces then the string was considered to be leading numeric.
Prior to PHP 8.0.0, when a string was used in a numeric context it would perform the same steps as above with the following differences:
E_NOTICEinstead of anE_WARNING.E_WARNINGwas raised and the value0would be returned.E_NOTICEnorE_WARNINGwas raised.<?php
$foo=1+"10.5";// $foo is float (11.5)
$foo=1+"-1.3e3";// $foo is float (-1299)
$foo=1+"bob-1.3e3";// TypeError as of PHP 8.0.0, $foo is integer (1) previously
$foo=1+"bob3";// TypeError as of PHP 8.0.0, $foo is integer (1) previously
$foo=1+"10 Small Pigs";// $foo is integer (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo=4+"10.2 Little Piggies";// $foo is float (14.2) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo="10.0 pigs "+1;// $foo is float (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo="10.0 pigs "+1.0;// $foo is float (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
?>Unarrayen PHP es en realidad un mapa ordenado. Un mapa es un tipo de datos que asociavaloresconclaves. Este tipo se optimiza para varios usos diferentes; se puede emplear como un array, lista (vector), tabla asociativa (tabla hash - una implementación de un mapa), diccionario, colección, pila, cola, y posiblemente más. Ya que los valores de unarraypueden ser otrosarrays, también son posibles árboles yarrays multidimensionales.
Una explicación sobre tales estructuras de datos está fuera del alcance de este manual, aunque se proporciona al menos un ejemplo de cada uno de ellos. Para más información, consulte la extensa literatura que existe sobre este amplio tema.
Unarraypuede ser creado con el constructor del lenguajearray(). Éste toma cualquier número de parejasclave=>valorcomo argumentos.
array(
clave => valor,
clave2 => valor2,
clave3 => valor3,
...
)La coma después del último elemento del array es opcional, pudiéndose omitir. Esto normalmente se hace para arrays de una única línea, es decir, es preferiblearray(1, 2)quearray(1, 2, ). Por otra parte, para arrays multilínea, la coma final se usa frecuentemente, ya que permite una adición más sencilla de nuevos elementos al final.
A partir de PHP 5.4 también se puede usar la sintaxis de array corta, la cual reemplazaarray()con[].
Ejemplo #1 Un array simple
<?php
$array= array(
"foo"=>"bar",
"bar"=>"foo",
);
// a partir de PHP 5.4
$array= [
"foo"=>"bar",
"bar"=>"foo",
];
?>Laclavepuede ser unintegero unstring. Elvalorpuede ser de cualquier tipo.
Además, se darán los siguientes amoldamientos declave:
+, será amoldado al tipointeger. Por ejemplo, la llave"8"será en realidad almacenado como8. Por otro lado"08"no será moldeado, ya que no es un entero decimal válido.8.7en realidad será almacenada como8.trueen realidad será almacenada como1y la clavefalsecomo0.nullen realidad será almacenada como"".Illegal offset type.Si varios elementos en la declaración del array usan la misma clave, sólo se utilizará la última, siendo los demás sobrescritos.
Ejemplo #2 Ejemplo de amoldamiento de tipo y sobrescritura
<?php
$array= array(
1=>"a",
"1"=>"b",
1.5=>"c",
true=>"d",
);
var_dump($array);
?>El resultado del ejemplo sería:
array(1) {
[1]=>
string(1) "d"
}
Como todas las claves en el ejemplo anterior se convierten en1, los valores serán sobrescritos en cada nuevo elemento, por lo que el último valor asignado"d"es el único que queda.
Los arrays de PHP pueden contener clavesintegerystringal mismo tiempo ya que PHP no distingue entre arrays indexados y asociativos.
Ejemplo #3 Claves mixtasintegerystring
<?php
$array= array(
"foo"=>"bar",
"bar"=>"foo",
100=> -100,
-100=>100,
);
var_dump($array);
?>El resultado del ejemplo sería:
array(4) {
["foo"]=>
string(3) "bar"
["bar"]=>
string(3) "foo"
[100]=>
int(-100)
[-100]=>
int(100)
}
Laclavees opcional. Si no se especifica, PHP usará el incremento de la clave de tipointegermayor utilizada anteriormente.
Ejemplo #4 Arrays indexados sin clave
<?php
$array= array("foo","bar","hello","world");
var_dump($array);
?>El resultado del ejemplo sería:
array(4) {
[0]=>
string(3) "foo"
[1]=>
string(3) "bar"
[2]=>
string(5) "hello"
[3]=>
string(5) "world"
}
Es posible especificar la clave sólo para algunos elementos y excluir a los demás:
Ejemplo #5 Claves no en todos los elementos
<?php
$array= array(
"a",
"b",
6=>"c",
"d",
);
var_dump($array);
?>El resultado del ejemplo sería:
array(4) {
[0]=>
string(1) "a"
[1]=>
string(1) "b"
[6]=>
string(1) "c"
[7]=>
string(1) "d"
}
Como se puede ver, al último valor"d"se le asignó la clave7. Esto es debido a que la mayor clave integer anterior era6.
Los elementos de array se pueden acceder utilizando la sintaxisarray[key].
Ejemplo #6 Acceso a elementos de un array
<?php
$array= array(
"foo"=>"bar",
42=>24,
"multi"=> array(
"dimensional"=> array(
"array"=>"foo"
)
)
);
var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>El resultado del ejemplo sería:
string(3) "bar" int(24) string(3) "foo"
Nota:
Tanto los corchetes como las llaves pueden ser utilizados de forma intercambiable para acceder a los elementos de un array (p.ej.:
$array[42]y$array{42}tendrán el mismo resultado en el ejemplo anterior).
A partir de PHP 5.4 es posible hacer referencia al array del resultado de una llamada a una función o método directamente. Antes sólo era posible utilizando una variable temporal.
Desde PHP 5.5 es posible hacer referencia directa un elemento de un array literal.
Ejemplo #7 Hacer referencia al resultado array de funciones
<?php
functiongetArray() {
return array(1,2,3);
}
// en PHP 5.4
$secondElement=getArray()[1];
// anteriormente
$tmp=getArray();
$secondElement=$tmp[1];
// o
list(,$secondElement) =getArray();
?>Nota:
Intentar acceder a una clave de un array que no se ha definido es lo mismo que el acceder a cualquier otra variable no definida: se emitirá un mensaje de error de nivel
E_NOTICE, y el resultado seránull.
Nota:
Array que dereferencia un valor escalar que no es unstringsilenciosamente arroja
null, es decir, sin emitir un mensaje de error.
Unarrayexistente puede ser modificado estableciendo explícitamente valores en él.
Esto se realiza asignando valores alarray, especificando la clave entre corchetes. Esta también se puede omitir, resultando en un par de corchetes vacíos ([]).
$arr[clave] = valor;
$arr[] = valor;
// clave puede ser un integer o un string
// valor puede ser cualquier valor de cualquier tipoSi$arraún no existe, se creará, siendo también esta forma una alternativa de crear unarray. Sin embargo, se desaconsejada esta práctica porque que si$arrya contiene algún valor (p.ej. unstringde una variable de petición), este estará en su lugar y[]puede significar realmente eloperador de acceso a strings. Siempre es mejor inicializar variables mediante una asignación directa.
Nota:A partir de PHP 7.1.0, la aplicación del operador de índice vacío en un string lanza un fatal error. Antes, el string se convertía silenciosamente en un array.
Para cambiar un valor determinado se debe asignar un nuevo valor a ese elemento empleando su clave. Para quitar una pareja clave/valor, se debe llamar a la funciónunset()con éste.
<?php
$arr= array(5=>1,12=>2);
$arr[] =56;// Esto es lo mismo que $arr[13] = 56;
// en este punto de el script
$arr["x"] =42;// Esto agrega un nuevo elemento a
// el array con la clave "x"
unset($arr[5]);// Esto elimina el elemento del array
unset($arr);// Esto elimina el array completo
?>Nota:
Como se mencionó anteriormente, si no se especifica una clave, se toma el máximo de los índicesintegerexistentes, y la nueva clave será ese valor máximo más 1 (aunque al menos 0). Si todavía no existen índicesinteger, la clave será
0(cero).Tenga en cuenta que la clave integer máxima utilizada para ésteno es necesario que actualmente exista en elarray. Ésta sólo debe haber existido en elarrayen algún momento desde la última vez que elarrayfué re-indexado. El siguiente ejemplo ilustra este comportamiento:
<?php
// Crear un array simple.
$array= array(1,2,3,4,5);
print_r($array);
// Ahora elimina cada elemento, pero deja el mismo array intacto:
foreach ($arrayas$i=>$value) {
unset($array[$i]);
}
print_r($array);
// Agregar un elemento (note que la nueva clave es 5, en lugar de 0).
$array[] =6;
print_r($array);
// Re-indexar:
$array=array_values($array);
$array[] =7;
print_r($array);
?>El resultado del ejemplo sería:
Array ( [0] => 1 [1] => 2 [2] => 3 [3] => 4 [4] => 5 ) Array ( ) Array ( [5] => 6 ) Array ( [0] => 6 [1] => 7 )
Hay un buen número de funciones útiles para trabajar con arrays. Véase la secciónfunciones de array.
Nota:
La funciónunset()permite remover claves de unarray. Tenga en cuenta que el arraynoes re-indexado. Si se desea un verdadero comportamiento "eliminar y desplazar", elarraypuede ser re-indexado usando la funciónarray_values().
<?php
$a= array(1=>'uno',2=>'dos',3=>'tres');
unset($a[2]);
/* producirá un array que se ha definido como
$a = array(1 => 'uno', 3 => 'tres');
y NO
$a = array(1 => 'uno', 2 =>'tres');
*/
$b=array_values($a);
// Ahora $b es array(0 => 'uno', 1 =>'tres')
?>
La estructura de controlforeachexiste específicamente paraarrays. Ésta provee una manera fácil de recorrer unarray.
$foo[bar]?Siempre deben usarse comillas alrededor de un índice de array tipo string literal. Por ejemplo,$foo['bar']es correcto, mientras que$foo[bar]no lo es. ¿Pero por qué? Es común encontrar este tipo de sintaxis en scripts viejos:
<?php
$foo[bar] ='enemy';
echo$foo[bar];
// etc
?>Esto está mal, pero funciona. La razón es que este código tiene una constante indefinida (bar) en lugar de unstring('bar'- observe las comillas). Funciona porque PHP automáticamente convierte unstring puro(unstringsin comillas que no corresponde con ningún símbolo conocido) en unstringque contiene elstringpuro. Por ejemplo, si no se ha definido una constante llamadabar, entonces PHP reemplazará su valor por elstring'bar'y usará éste último.
La alternativa de tratar una constante indefinida como string vacío está obsoleto a partir de PHP 7.2.0, y emite un error de nivelE_WARNING. Anteriormente, un error de nivelE_NOTICEera emitido.
Nota:Esto no quiere decir quesiemprehaya que usar comillas en la clave. No use comillas con claves que seanconstantesovariables, ya que en tal caso PHP no podrá interpretar sus valores.
<?php
error_reporting(E_ALL);
ini_set('display_errors',true);
ini_set('html_errors',false);
// Array simple:
$array= array(1,2);
$count=count($array);
for ($i=0;$i<$count;$i++) {
echo"\nRevisando$i: \n";
echo"Mal: ".$array['$i'] ."\n";
echo"Bien: ".$array[$i] ."\n";
echo"Mal:{$array['$i']}\n";
echo"Bien:{$array[$i]}\n";
}
?>El resultado del ejemplo sería:
Revisando 0: Notice: Undefined index: $i in /path/to/script.html on line 9 Mal: Bien: 1 Notice: Undefined index: $i in /path/to/script.html on line 11 Mal: Bien: 1 Revisando 1: Notice: Undefined index: $i in /path/to/script.html on line 9 Mal: Bien: 2 Notice: Undefined index: $i in /path/to/script.html on line 11 Mal: Bien: 2
Más ejemplos para demostrar este comportamiento:
<?php
// Mostrar todos los errores
error_reporting(E_ALL);
$arr= array('fruit'=>'apple','veggie'=>'carrot');
// Correcto
print$arr['fruit'];// apple
print$arr['veggie'];// carrot
// Incorrecto. Esto funciona pero también genera un error de PHP de
// nivel E_NOTICE ya que no hay definida una constante llamada fruit
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print$arr[fruit];// apple
// Esto define una constante para demostrar lo que pasa. El valor 'veggie'
// es asignado a una constante llamada fruit.
define('fruit','veggie');
// Note la diferencia ahora
print$arr['fruit'];// apple
print$arr[fruit];// carrot
// Lo siguiente está bien ya que se encuentra al interior de una cadena. Las constantes no son procesadas al
// interior de cadenas, así que no se produce un error E_NOTICE aquí
print"Hello$arr[fruit]";// Hello apple
// Con una excepción, los corchetes que rodean las matrices al
// interior de cadenas permiten el uso de constantes
print"Hello{$arr[fruit]}";// Hello carrot
print"Hello{$arr['fruit']}";// Hello apple
// Esto no funciona, resulta en un error de intérprete como:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// Esto por supuesto se aplica también al uso de superglobales en cadenas
print"Hello$arr['fruit']";
print"Hello$_GET['foo']";
// La concatenación es otra opción
print"Hello ".$arr['fruit'];// Hello apple
?>Cuando se habilitaerror_reportingpara mostrar errores de nivelE_NOTICE(como por ejemplo definiendo el valorE_ALL), este tipo de usos serán inmediatamente visibles. Por omisión,error_reportingse encuentra configurado para no mostrarlos.
Tal y como se indica en la sección desintaxis, lo que existe entre los corchetes cuadrados ('[' y ']') debe ser una expresión. Esto quiere decir que código como el siguiente funciona:
<?php
echo$arr[somefunc($bar)];
?>Este es un ejemplo del uso de un valor devuelto por una función como índice del array. PHP también conoce las constantes:
<?php
$error_descriptions[E_ERROR] ="Un error fatal ha ocurrido";
$error_descriptions[E_WARNING] ="PHP produjo una advertencia";
$error_descriptions[E_NOTICE] ="Esta es una noticia informal";
?>Note queE_ERRORes también un identificador válido, asi comobaren el primer ejemplo. Pero el último ejemplo es equivalente a escribir:
<?php
$error_descriptions[1] ="Un error fatal ha ocurrido";
$error_descriptions[2] ="PHP produjo una advertencia";
$error_descriptions[8] ="Esta es una noticia informal";
?>ya queE_ERRORes igual a1, etc.
En algún momento en el futuro, puede que el equipo de PHP quiera usar otra constante o palabra clave, o una constante proveniente de otro código puede interferir. Por ejemplo, en este momento no puede usar las palabrasemptyydefaultde esta forma, ya que sonpalabras clave reservadas.
Nota:Reiterando, al interior de un valorstringentre comillas dobles, es válido no rodear los índices de array con comillas, así que
"$foo[bar]"es válido. Consulte los ejemplos anteriores para más detalles sobre el porqué, así como la sección sobreprocesamiento de variables en cadenas.
Para cualquiera de los tiposinteger,float,string,booleanyresource, convertir un valor a unarrayresulta en un array con un solo elemento, con índice 0, y el valor del escalar que fue convertido. En otras palabras,(array)$scalarValuees exactamente lo mismo quearray($scalarValue).
Si convierte unobjecta unarray, el resultado es unarraycuyos elementos son las propiedades delobject. Las claves son los nombres de las variables miembro, con algunas excepciones notables: las variables privadas tienen el nombre de la clase al comienzo del nombre de la variable; las variables protegidas tienen un caracter '*' al comienzo del nombre de la variable. Estos valores adicionados al inicio tienen bytesNULa los lados. Laspropiedades tipificadasno inicializadas se descartan silenciosamente.
<?php
classA{
private$A;// Este campo se convertirá en '\0A\0A'
}
classBextendsA{
private$A;// Este campo se convertirá en '\0B\0A'
public$AA;// Este campo se convertirá en 'AA'
}
var_dump((array) newB());
?>En el ejemplo anterior parecerá que se tienen dos claves llamadas 'AA', aunque en realidad una de ellas se llama '\0A\0A'.
Si convierte un valornullaarray, obtiene unarrayvacío.
Es posible comparar arrays con la funciónarray_diff()y medianteoperadores de arrays.
El tipo array en PHP es bastante versátil. Aquí hay algunos ejempos:
<?php
// Esto:
$a= array('color'=>'red',
'taste'=>'sweet',
'shape'=>'round',
'name'=>'apple',
4// la clave será 0
);
$b= array('a','b','c');
// . . .es completamente equivalente a
$a= array();
$a['color'] ='red';
$a['taste'] ='sweet';
$a['shape'] ='round';
$a['name'] ='apple';
$a[] =4;// la clave será 0
$b= array();
$b[] ='a';
$b[] ='b';
$b[] ='c';
// Después de que se ejecute el código, $a será el array
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
// 'name' => 'apple', 0 => 4), y $b será el array
// array(0 => 'a', 1 => 'b', 2 => 'c'), o simplemente array('a', 'b', 'c').
?>Ejemplo #8 Uso de array()
<?php
// Array como mapa de propiedades
$map= array('version'=>4,
'OS'=>'Linux',
'lang'=>'english',
'short_tags'=>true
);
// Keys estrictamente numéricas
$array= array(7,
8,
0,
156,
-10
);
// esto es lo mismo que array(0 => 7, 1 => 8, ...)
$switching= array(10,// key = 0
5=>6,
3=>7,
'a'=>4,
11,// key = 6 (el índice entero máximo era 5)
'8'=>2,// key = 8 (integer!)
'02'=>77,// key = '02'
0=>12// el valor 10 será reemplazado por 12
);
// array vacío
$empty= array();
?>Ejemplo #9 Colección
<?php
$colors= array('rojo','azul','verde','amarillo');
foreach ($colorsas$color) {
echo"¿Le gusta el$color?\n";
}
?>El resultado del ejemplo sería:
¿Le gusta el rojo? ¿Le gusta el azul? ¿Le gusta el verde? ¿Le gusta el amarillo?
Modificar los valores delarraydirectamente es posible pasándolos por referencia.
Ejemplo #10 Cambiando elemento en el bucle
<?php
foreach ($colorsas &$color) {
$color=strtoupper($color);
}
unset($color);/* se asegura de que escrituras subsiguientes a $color
no modifiquen el último elemento del arrays */
print_r($colors);
?>El resultado del ejemplo sería:
Array
(
[0] => ROJO
[1] => AZUL
[2] => VERDE
[3] => AMARILLO
)
Este ejemplo crea un array con base uno.
Ejemplo #11 Índice con base 1
<?php
$firstquarter= array(1=>'Enero','Febrero','Marzo');
print_r($firstquarter);
?>El resultado del ejemplo sería:
Array
(
[1] => 'Enero'
[2] => 'Febrero'
[3] => 'Marzo'
)
Ejemplo #12 Llenado de un array
<?php
// llenar un array con todos los ítems de un directorio
$handle=opendir('.');
while (false!== ($file=readdir($handle))) {
$files[] =$file;
}
closedir($handle);
?>LosArrays son ordenados. El orden puede ser modificado usando varias funciones de ordenado. Vea la sección sobrefunciones de arrayspara más información. La funcióncount()puede ser usada para contar el número de elementos en unarray.
Ejemplo #13 Ordenado de un array
<?php
sort($files);
print_r($files);
?>Dado que el valor de unarraypuede ser cualquier cosa, también puede ser otroarray. De esta forma es posible creararrays recursivas y multi-dimensionales.
Ejemplo #14 Arrays recursivos y multi-dimensionales
<?php
$fruits= array ("fruits"=> array ("a"=>"orange",
"b"=>"banana",
"c"=>"apple"
),
"numbers"=> array (1,
2,
3,
4,
5,
6
),
"holes"=> array ("first",
5=>"second",
"third"
)
);
// Algunos ejemplos que hacen referencia a los valores del array anterior
echo$fruits["holes"][5];// prints "second"
echo$fruits["fruits"]["a"];// prints "orange"
unset($fruits["holes"][0]);// remove "first"
// Crear una nueva array multi-dimensional
$juices["apple"]["green"] ="good";
?>La asignación dearrays siempre involucra la copia de valores. Use eloperador de referenciapara copiar unarraypor referencia.
<?php
$arr1= array(2,3);
$arr2=$arr1;
$arr2[] =4;// $arr2 ha cambiado,
// $arr1 sigue siendo array(2, 3)
$arr3= &$arr1;
$arr3[] =4;// ahora $arr1 y $arr3 son iguales
?>Iterablees un seudotipo introducido en PHP 7.1. Acepta cualquierarrayu objeto que implemente la interfazTraversable. Estos dos tipos se recorren conforeachy se pueden emplear conyield fromdentro de ungenerador.
Iterable se puede usar como tipo de parámetro para indicar que una función requiere un conjunto de valores, pero que no importa la forma del dicho conjunto ya que se utiizará conforeach. Si un valor no es un array o una instancia deTraversable, se lanzará unTypeError.
Ejemplo #1 Ejemplo de de tipo de parámetro iterable
<?php
functionfoo(iterable $iterable) {
foreach ($iterableas$valor) {
// ...
}
}
?>Los parámetros declarados como iterable pueden usarnullo un array como valor predeterminado.
Ejemplo #2 Ejemplo de valor predeterminado de un parámetro iterable
<?php
functionfoo(iterable $iterable= []) {
// ...
}
?>Iterable se puede usar como tipo de retorno para indicar que una función devolverá un valor iterable. Si el valor devuelto no es un array o una instancia deTraversable, se lanzará unTypeError.
Ejemplo #3 Ejemplo de tipo de retorno iterable
<?php
functionbar():iterable{
return [1,2,3];
}
?>Las funciones que declaren su tipo de retorno como también pueden sergeneradores.
Ejemplo #4 Ejemplo de tipo de retorno de generadro iterable
<?php
functiongen():iterable{
yield1;
yield2;
yield3;
}
?>Las clases que extiendan/implementen podrían ampliar los métodos usandoarrayoTraversablecomo tipos de parámetro aiterableo reducir los tipos de retorno deiterableaarrayoTraversable.
Ejemplo #5 Ejemplo de varianza del tipo iterable
<?php
interfaceEjemplo{
public functionmethod(array$array):iterable;
}
classImplementaciónDeEjemploimplementsEjemplo{
public functionmethod(iterable $iterable): array {
// Parámetro ampliado y tipo de retorno reducido.
}
}
?>Para crear un nuevoobject, utilice la sentencianewpara instanciar una clase:
<?php
classfoo
{
functionhacer_algo()
{
echo"Haciendo algo.";
}
}
$bar= newfoo;
$bar->hacer_algo();
?>Para una descripción completa, véase el capítuloClases y objetos.
Si unobjectse convierte en unobject, éste no se modifica. Si un valor de cualquier otro tipo se convierte en unobject, se crea una nueva instancia de la clasestdClassincorporada. Si el valor esnull, la nueva instancia estará vacía. Unarrayse convierte en unobjectcon las propiedades nombradas como claves y los valores correspondientes, con la excepción de las claves numéricas, las cuales serán inaccesibles a menos que sean recorridas.
<?php
$obj= (object) array('1'=>'foo');
var_dump(isset($obj->{'1'}));// muestra 'bool(false)'
var_dump(key($obj));// muestra 'int(1)'
?>Para cualquier otro valor, una variable miembro llamadascalarcontendrá el valor.
<?php
$obj= (object)'ciao';
echo$obj->scalar;// muestra 'ciao'
?>Un valor tiporesourcees una variable especial, que contiene una referencia a un recurso externo. Los recursos son creados y usados por funciones especiales. Vea elapéndicepara un listado de todas estas funciones y los tiposresourcecorrespondientes.
Vea también la funciónget_resource_type().
Dado que las variablesresourcecontienen gestores especiales a archivos abiertos, conexiones con bases de datos, áreas de pintura de imágenes y cosas por el estilo, la conversión a tiporesourcecarece de sentido.
Gracias al sistema de conteo de referencias introducido con el Motor Zend, un recurso que ya no es referenciado es detectado automáticamente, y es liberado por el recolector de basura. Por esta razón, rara vez se necesita liberar la memoria manualmente.
Nota:Los enlaces persistentes con bases de datos son una excepción a esta regla. Ellosnoson destruidos por el recolector de basura. Vea también la sección sobreconexiones persistentespara más información.
El valor especialnullrepresenta una variable sin valor.nulles el único valor posible del tiponull.
Una variable es consideradanullsi:
se le ha asignado la constantenull.
no se le ha asignado un valor todavía.
se ha destruido conunset().
No hay más que un valor de tiponull, y es la constantenullinsensible a mayúsculas/minúsculas.
<?php
$var=NULL;
?>nullEsta característica ha sido declaradaOBSOLETAa partir de PHP 7.2.0. Su uso está totalmente desaconsejado.
Convertir una variable anullusando(unset) $varnoeliminará la variable ni destruirá su valor. Sólo retornará un valornull.
Las llamadas de retorno, o retrollamadas, se pueden indicar con la declaración de tipocallablea partir de PHP 5.4. Esta documentación utilizó la información del tipocallbackcon el mismo propósito.
Algunas funciones comocall_user_func()ousort()aceptan como parámetro funciones de llamada de retorno definidas por el usuario. Las funciones de llamadas de retorno no sólo pueden ser funciones simples, sino también métodos de unobject, incluyendo métodos de clase estáticos.
Una función de PHP se pasa por su nombre como unstring. Se puede utilizar cualquier función nativa o definida por el usuario, exceptuando contrucciones del lenguaje, tales como:array(),echo,empty(),eval(),exit(),isset(),list(),printounset().
Un método de unobjectinstanciado se pasa como unarrayque contiene unobjecten el índice 0 y el nombre del método en el índice 1. Está permitido el acceso a métodos protegidos y privados desde dentro de una clase.
Los métodos de clase estáticos también se pueden pasar sin instanciar unobjectde dicha clase, pasando el nombre de la clase en lugar de unobjecten el índice 0. A partir de PHP 5.2.3, también es posible pasar'NombreDeClase::nombreDeMetodo'.
A parte de las funciones comunes definidas por el usuario, lasfunciones anónimastambién se pueden pasar a un parámetro de llamada de retorno.
Ejemplo #1 Ejemplos de funciones de llamadas de retorno
<?php
// Un ejemplo de función de llamada de retorno
functionmi_función_de_llamada_de_retorno() {
echo'¡hola mundo!';
}
// Un ejemplo de método de llamada de retorno
classMiClase{
static functionmiMétodoDeLlamadaDeRetorno() {
echo'¡Hola Mundo!';
}
}
// Tipo 1: Llamada de retorno simple
call_user_func('mi_función_de_llamada_de_retorno');
// Tipo 2: Llamada a un método de clase estático
call_user_func(array('MiClase','miMétodoDeLlamadaDeRetorno'));
// Tipo 3: Llamada al método de un objeto
$obj= newMiClase();
call_user_func(array($obj,'miMétodoDeLlamadaDeRetorno'));
// Tipo 4: Llamada a un método de clase estático (A partir de PHP 5.2.3)
call_user_func('MiClase::miMétodoDeLlamadaDeRetorno');
// Tipo 5: Llamada a un método de clase estático relativo (A partir de PHP 5.3.0)
classA{
public static functionquién() {
echo"A\n";
}
}
classBextendsA{
public static functionquién() {
echo"B\n";
}
}
call_user_func(array('B','parent::quién'));// A
// Tipe 6: Los objetos que implementan __invoke se pueden emplear como retrollamadas (desde PHP 5.3)
classC{
public function__invoke($nombre) {
echo'Hola ',$nombre,"\n";
}
}
$c= newC();
call_user_func($c,'PHP!');
?>Ejemplo #2 Ejemplo de retrollamada utilizando un cierre
<?php
// Nuestro cierre
$doble= function($a) {
return$a*2;
};
// Este es nuestro rango de números
$números=range(1,5);
// Usar el cierre como llamada de retorno para
// doblar el valor de cada elemento de nuestro
// rango
$números_nuevos=array_map($doble,$números);
printimplode(' ',$números_nuevos);
?>El resultado del ejemplo sería:
2 4 6 8 10
Nota:
Las funciones de retorno de llamada que se registran con funciones comocall_user_func()ycall_user_func_array()no se llamarán si se produce una excepción en la función de retorno previa.
Las declaraciones de tipo pueden ser añadidas a los argumentos de función, valores de retorno y desde PHP 7.4.0, propiedades de clase. Éstas declaraciones aseguran que el valor es del tipo especificado en el momento de la llamada, de no ser así se lanzará una excepción de tipoTypeError.
Nota:
Cuando se sobreescribe el método de un padre, el método hijo debe coincidir con cualquier tipo de declaración de retorno del padre. Si el padre no tiene definida un tipo de retorno, entonces el método hijo puede realizarla.
| Tipo | Descripción | Versión |
|---|---|---|
| Nombre de la Clase/Interfaz | El valor debe ser una instancia de la clase o de la interfaz. | |
| self | El valor debe ser unainstanceofde la misma clase que aquella en la que se utiliza la declaración de tipo. Solamente se puede usar en clases. | |
| parent | El valor debe ser unainstanceofdel padre de la clase en la que se usa la declaración de tipo. Solo se puede usar en clases. | |
| array | El valor debe ser unarray. | |
| callable | El valor debe ser uncallableválido. No puede ser usado como una declaración de tipo de propiedad de clase. | |
| bool | El valor debe ser un valor booleano. | |
| float | El valor debe ser un número de coma flotante. | |
| int | El valor debe ser un número entero. | |
| string | El valor debe ser unstring. | |
| iterable | El valor debe ser unarrayo unainstanceofde la claseTraversable. | PHP 7.1.0 |
| object | El valor debe ser unobjeto. | PHP 7.2.0 |
| mixed | El valor puede ser cualquier valor. | PHP 8.0.0 |
No se admiten los alias para los tipos escalares anteriores. En su lugar, se tratan como nombres de clase o interfaz. Por ejemplo, usarbooleancomo declaración de tipo requerirá que el valor sea unainstanceofde clase o interfazboolean, en lugar de tipobool:
<?php
functiontest(boolean $parametro) {}
test(true);
?>Output of the above example in PHP 8:
Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2
Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
Stack trace:
#0 -(3): test(true)
#1 {main}
thrown in - on line 2
mixedes equivalente aunion typeobject|resource|array|string|int|float|bool|null. Disponible a partir de PHP 8.0.0.
Ejemplo #1 Declaración de tipo de clase básica
<?php
classC{}
classDextendsC{}
// Esta clase no extiende de C.
classE{}
functionf(C $c) {
echoget_class($c)."\n";
}
f(newC);
f(newD);
f(newE);
?>Output of the above example in PHP 8:
C
D
Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
thrown in - on line 8
Ejemplo #2 Declaración de tipo de interfaz básica
<?php
interfaceI{ public functionf(); }
classCimplementsI{ public functionf() {} }
// Esta clase no implementa I.
classE{}
functionf(I $i) {
echoget_class($i)."\n";
}
f(newC);
f(newE);
?>Output of the above example in PHP 8:
C
Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
thrown in - on line 8
Ejemplo #3 Declaración de tipo de retorno básica
<?php
functionsuma($a,$b):float{
return$a+$b;
}
// Se devolverá un valor float.
var_dump(suma(1,2));
?>El resultado del ejemplo sería:
float(3)
Ejemplo #4 Retornando un objeto
<?php
classC{}
functiongetC():C{
return newC;
}
var_dump(getC());
?>El resultado del ejemplo sería:
object(C)#1 (0) {
}
A partir de PHP 7.1.0, las declaraciones de tipo pueden ser marcadas como nullable anteponiendo un interrogante(?) en el nombre de tipo. Esto conlleva a que el valor puede ser del tipo específico onull.
Ejemplo #5 Declaración de tipo de argumento Nullable
<?php
classC{}
functionf(?C $c) {
var_dump($c);
}
f(newC);
f(null);
?>El resultado del ejemplo sería:
object(C)#1 (0) {
}
NULL
Ejemplo #6 Declaración de tipo de retorno Nullable
<?php
functionget_item(): ?string{
if (isset($_GET['item'])) {
return$_GET['item'];
} else {
returnnull;
}
}
?>Nota:
Es posible lograr argumentos anulables haciendo
nullel valor por defecto. Esto no se recomienda ya que se rompe durante la herencia.Ejemplo #7 Forma antigua de hacer argumentos nullable por defecto
<?php
classC{}
functionf(C $c=null) {
var_dump($c);
}
f(newC);
f(null);
?>El resultado del ejemplo sería:
object(C)#1 (0) { } NULL
Es posible combinar tipos simples en tipos compuestos. PHP permite combinar tipos de las siguientes maneras:
No es posible combinar tipos intersección con tipos unión.
Una declaración de tipo de unión acepta valores de múltiples tipos simples diferentes, en lugar de uno solo. Los tipos de unión se especifican mediante la sintaxisT1|T2|.... Los tipos de unión están disponibles a partir de PHP 8.0.0.
El tiponullse admite como parte de las uniones, de modo queT1|T2|nullse puede usar para crear una unión nullable. La notación?Texistente se considera una forma abreviada del caso común deT|null.
nullno puede ser usado como tipo standalone.
Thefalseliteral type is supported as part of unions, and is included as for historical reasons many internal functions returnfalseinstead ofnullfor failures. A classic example of such a function isstrpos().
falseno se puede usar como tipo independiente (incluido tipo independiente nullable). Por este motivofalse,false|nully?falseno están permitidos.
El literaltruenoexiste.
Una declaración de tipo de Intersección acepta valores que satisfacen múltiples declaraciones de tipo de clase, en lugar de una sola. Los tipos Intersección se especifican usando la sintaxisT1&T2&...Los tipos Intersección están disponibles a partir de PHP 8.1.0.
Para detectar errores simples en declaraciones de tipos compuestos, los tipos redundantes que se puedan detectar sin realizar la carga de clase dará como resultado un error en tiempo de compilación. Esto incluye:
int|string|INToCountable&Traversable&COUNTABLEdarán como resultado un error.Nota:Esto no garantiza que el tipo sea "mínimo", porque hacerlo requeriría cargar todos los tipos de clase usados.
Por ejemplo, siAyBson alias de clase, entoncesA|Bsigue siendo un tipo de unión legal, aunque podría reducirse aAoB. De manera similar, si la claseB extends A {}, entoncesA|Bes también un tipo de unión legal, aunque podría reducirse a soloA.
<?php
functionfoo():int|INT{}// No permitido
functionfoo():bool|false{}// No permitido
functionfoo():int&Traversable{}// No permitido
functionfoo():self&Traversable{}// No permitido
useAasB;
functionfoo():A|B{}// No permitido ("use" es parte de la resolución del nombre)
functionfoo():A&B{}// No permitido ("use" es parte de la resolución del nombre)
class_alias('X','Y');
functionfoo():X|Y{}// Permitido (La redundancia solo se detecta en tiempo de ejecución)
functionfoo():X&Y{}// Permitido (La redundancia solo se detecta en tiempo de ejecución)
?>voides un tipo de retorno que indica que la función no devuelve un valor. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 7.1.0.
Nota:
Queda obsoleto el retorno por referencia desde una funcionvoida partir de PHP 8.1.0, debido a que dicha función es contradictoria. Previamente emitía el siguiente
E_NOTICEcuando se llamaba:Only variable references should be returned by reference<?php
function &test():void{}
?>
neveres un tipo de retorno que indica que la función no retorna. Esto significa que llama aexit(), lanza una excepción o es un ciclo infinito. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 8.1.0.
neveres, en el lenguaje de la teoría de tipos, el tipo inferior. Lo que significa que es el subtipo de cualquier otro tipo y puede reemplazar cualquier otro tipo de retorno durante la herencia.
El valor debe ser una instancia de la misma clase en la que se llama al método. Disponible a partir de PHP 8.0.0.
Por defecto, PHP forzará los valores del tipo incorrecto en la declaración de tipo escalar esperada si es posible. Por ejemplo, una función a la que se le da unintpara un parámetro que espera unastringobtendrá una variable de tipostring.
Es posible habilitar el modo estricto por archivo. En modo estricto, solo se aceptará un valor que corresponda exactamente a la declaración de tipo. De lo contrario, se lanzará unTypeError. La única excepción a esta regla es que un valorintpasará una declaración de tipofloat.
Las llamadas a funciones desde funciones internas no se verán afectadas por la declaración destrict_types.
Para habilitar el modo estricto, se usa el constructordeclarecon la declaraciónstrict_types=1.
Nota:
El tipado estricto se aplica a las llamadas de función realizadas desde dentro del archivo con el tipado estricto habilitado, no a las funciones declaradas de ese archivo. Si un archivo sin
strict_typesactivado realiza una llamada a una función que se definió en un archivo constrict_typesactivado, la preferencia será respetada (escritura coercitiva) y se forzará el valor.
Nota:
La tipificación estricta solo está definida para declaraciones de tipos escalares.
Ejemplo #8 Tipificación estricta para los valores de los argumentos
<?php
declare(strict_types=1);
functionsuma(int $a,int $b) {
return$a+$b;
}
var_dump(suma(1,2));
var_dump(suma(1.5,2.5));
?>Output of the above example in PHP 8:
int(3)
Fatal error: Uncaught TypeError: suma(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
thrown in - on line 4
Ejemplo #9 Tipificación coercitiva para valores de los argumentos
<?php
functionsuma(int $a,int $b) {
return$a+$b;
}
var_dump(suma(1,2));
// Estos serán forzados a números enteros: ¡observe el resultado a continuación!
var_dump(suma(1.5,2.5));
?>El resultado del ejemplo sería:
int(3) int(3)
Ejemplo #10 Tipificación estricta para valores de retorno
<?php
declare(strict_types=1);
functionsuma($a,$b):int{
return$a+$b;
}
var_dump(suma(1,2));
var_dump(suma(1,2.5));
?>El resultado del ejemplo sería:
int(3)
Fatal error: Uncaught TypeError: suma(): Return value must be of type int, float returned in -:5
Stack trace:
#0 -(9): suma(1, 2.5)
#1 {main}
thrown in - on line 5
Cuandostrict_typesno está activado, las declaraciones de tipo escalar están sujetas a coerciones de tipo limitadas. Si el tipo exacto del valor no es parte de la unión, entonces el tipo de destino se elige en el siguiente orden de preferencia:
Como excepción, si el valor es una cadena y tanto int como float son parte de la unión, el tipo preferido está determinado por la semántica de "cadena numérica" existente. Por ejemplo, para"42"se eligeint, mientras que para"42.0"se eligefloat.
Nota:
Los tipos que no forman parte de la lista de preferencias anterior no son objetivos elegibles para la coerción implícita. En particular, no ocurre ninguna coerción implícita para los tipos
nullyfalse.
Ejemplo #11 Ejemplo de tipos siendo forzados a formar parte del tipo Unión
<?php
// int|string
42-->42// tipo exacto
"42"-->"42"// tipo exacto
newObjectWithToString-->"Resultado de __toString()"
// object nunca compatible con int, se resuelve como string
42.0-->42// float compatible con int
42.1-->42// float compatible con int
1e100-->"1.0E+100"// float demasiado largo para tipo int, se resuelve como string
INF-->"INF"// float demasiado largo para tipo int, se resuelve como string
true-->1// bool compatible con int
[] -->TypeError// array no compatible con int o string
// int|float|bool
"45"-->45// string numérico int
"45.0"-->45.0// string numérico float
"45X"-->true// no es string numérico, se resuelve como bool
""-->false// no es string numérico, se resuelve como bool
"X"-->true// no es string numérico, se resuelve como bool
[] -->TypeError// array no compatible con int, float or bool
?>Ejemplo #12 Tipificación de parámetros pasados por referencia
Los tipos declarados de parámetros pasados por referencia se verifican en la entrada de la función, pero no cuando la función devuelve el retorno, por lo que después de que la función haya devuelvo el retorno, el tipo de argumento puede haber cambiado.
<?php
functionarray_baz(array &$param)
{
$param=1;
}
$var= [];
array_baz($var);
var_dump($var);
array_baz($var);
?>Output of the above example in PHP 8:
int(1)
Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
Stack trace:
#0 -(9): array_baz(1)
#1 {main}
thrown in - on line 2
Ejemplo #13 CapturandoTypeError
<?php
declare(strict_types=1);
functionsuma(int $a,int $b) {
return$a+$b;
}
try {
var_dump(suma(1,2));
var_dump(suma(1.5,2.5));
} catch (TypeError $e) {
echo'Error: ',$e->getMessage();
}
?>Output of the above example in PHP 8:
int(3) Error: suma(): Argument #1 ($a) must be of type int, float given, called in - on line 10
PHP no requiere (ni soporta) la definición explicita de tipos en la declaración de variables; el tipo de la variable se determina por el contexto en el cual se emplea la variable. Es decir, si se asigna un valorstringa una variable$var, entonces$varse convierte en unstring. Si un valorintegeres entonces asignado a la misma variable$var, ésta se convierte eninteger.
Un ejemplo de la conversión de tipos automática de PHP es el operador suma '+'. Si al menos uno de los operandos esfloat, entonces ambos operandos son evaluados comofloats y el resultado será unfloat. De otra manera, los operandos seran interpretados comointegers, y el resultado será entoncesinteger. Tenga en cuenta que estonoimplica que se cambien los tipos de los propios operandos; el único cambio es en como se evalúan los operandos y en el tipo de expresión en sí mismo.
<?php
$foo="0";// $foo es string (ASCII 48)
$foo+=2;// $foo es ahora un integer (2)
$foo=$foo+1.3;// $foo es ahora un float (3.3)
$foo=5+"10 Cerditos pequeñitos";// $foo es integer (15)
$foo=5+"10 Cerdos pequeños";// $foo es integer (15)
?>Si considera confusos los últimos dos ejemplos anteriores, consulteConversión de cadenas a números.
Para forzar a que una variable sea evaluada como un determinado tipo, consulte la secciónForzado de tipos. Para cambiar el tipo de variable, consulte la funciónsettype().
Para probar cualquiera de los ejemplos de esta sección, utilice la funciónvar_dump().
Nota:
El comportamiento de la conversión automática enarrayestá actualmente sin definir.
Tambien, debido a que PHP soporta el indexado destringmediante compensaciones mediante la misma sintaxis empleada en el indexado dearrays, los siguientes ejemplos son válidos para todas las versiones de PHP:
<?php
$a='car';// $a es un string
$a[0] ='b';// $a sigue siendo un string
echo$a;// bar
?>Consulte la secciónAcceso a cadenas mediante caracterespara más información.
El forzado de tipos en PHP funciona de la misma manera que en C:, donde el nombre del tipo deseado se escribe entre paréntesis antes de la variable que se quiera forzar.
<?php
$foo=10;// $foo es un integer
$bar= (boolean)$foo;// $bar es un boolean
?>Los siguientes forzados de tipos están permitidos:
El forzado (binary) y el soporte del prefijo b fueron añadidos en PHP 5.2.1
Fíjese que se permiten las tabulaciones y espacios dentro de los paréntesis, por lo que los siguientes ejemplos son funcionalmente equivalentes:
<?php
$foo= (int)$bar;
$foo= ( int )$bar;
?>Forzado literal destrings y variables astrings binarios:
<?php
$binary= (binary)$string;
$binary=b"binary string";
?>Nota:
El lugar de forzar una variable astring, tambien se puede encerrar la variable entre comillas dobles.
<?php
$foo=10;// $foo es un integer
$str="$foo";// $str es un string
$fst= (string)$foo;// $fst es tambien un string
// Esto muestra que "son lo mismo"
if ($fst===$str) {
echo"son lo mismo";
}
?>
Puede que no sea obvio que sucede exactamente cuando se fuerzan ciertos tipos. Para más información, consulte estas secciones:
En PHP las variables se representan con un signo de dólar seguido por el nombre de la variable. El nombre de la variable es sensible a minúsculas y mayúsculas.
Los nombres de variables siguen las mismas reglas que otras etiquetas en PHP. Un nombre de variable válido tiene que empezar con una letra o un carácter de subrayado (underscore), seguido de cualquier número de letras, números y caracteres de subrayado. Como expresión regular se podría expresar como: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Nota:Para los propósitos de este manual, una letra es a-z, A-Z, y los bytes del 127 al 255 (
0x7f-0xff).
Nota:
$thises una variable especial que no puede ser asignada.
Vea tambiénGuía de entorno de usuario para nombres.
Para más información sobre funciones relacionadas con variables, vea laReferencia de Funciones de Variables.
<?php
$var='Roberto';
$Var='Juan';
echo"$var,$Var";// imprime "Roberto, Juan"
$4site='aun no';// inválido; comienza con un número
$_4site='aun no';// válido; comienza con un carácter de subrayado
$täyte='mansikka';// válido; 'ä' es ASCII (Extendido) 228
?>De forma predeterminada, las variables siempre se asignan por valor. Esto significa que cuando se asigna una expresión a una variable, el valor completo de la expresión original se copia en la variable de destino. Esto quiere decir que, por ejemplo, después de asignar el valor de una variable a otra, los cambios que se efectúen a una de esas variables no afectará a la otra. Para más información sobre este tipo de asignación, veaExpresiones.
PHP también ofrece otra forma de asignar valores a las variables:asignar por referencia. Esto significa que la nueva variable simplemente referencia (en otras palabras, "se convierte en un alias de" ó "apunta a") la variable original. Los cambios a la nueva variable afectan a la original, y viceversa.
Para asignar por referencia, simplemente se antepone un signo ampersand (&) al comienzo de la variable cuyo valor se está asignando (la variable fuente). Por ejemplo, el siguiente segmento de código produce la salida 'Mi nombre es Bob' dos veces:
<?php
$foo='Bob';// Asigna el valor 'Bob' a $foo
$bar= &$foo;// Referenciar $foo vía $bar.
$bar="Mi nombre es$bar";// Modifica $bar...
echo$bar;
echo$foo;// $foo también se modifica.
?>Algo importante a tener en cuenta es que sólo las variables con nombre pueden ser asignadas por referencia.
<?php
$foo=25;
$bar= &$foo;// Esta es una asignación válida.
$bar= &(24*7);// Inválida; referencia una expresión sin nombre.
functiontest()
{
return25;
}
$bar= &test();// Inválido.
?>No es necesario inicializar variables en PHP, sin embargo, es una muy buena práctica. Las variables no inicializadas tienen un valor predeterminado de acuerdo a su tipo dependiendo del contexto en el que son usadas - las booleanas se asumen comofalse, los enteros y flotantes como cero, las cadenas (p.ej. usadas enecho) se establecen como una cadena vacía y los arrays se convierten en un array vacío.
Ejemplo #1 Valores predeterminados en variables sin inicializar
<?php
// Una variable no definida Y no referenciada (sin contexto de uso); imprime NULL
var_dump($variable_indefinida);
// Uso booleano; imprime 'false' (Vea operadores ternarios para más información sobre esta sintaxis)
echo($booleano_indefinido?"true\n":"false\n");
// Uso de una cadena; imprime 'string(3) "abc"'
$cadena_indefinida.='abc';
var_dump($cadena_indefinida);
// Uso de un entero; imprime 'int(25)'
$int_indefinido+=25;// 0 + 25 => 25
var_dump($int_indefinido);
// Uso de flotante/doble; imprime 'float(1.25)'
$flotante_indefinido+=1.25;
var_dump($flotante_indefinido);
// Uso de array; imprime array(1) { [3]=> string(3) "def" }
$array_indefinida[3] ="def";// array() + array(3 => "def") => array(3 => "def")
var_dump($array_indefinida);
// Uso de objetos; crea un nuevo objeto stdClass (vea http://www.php.net/manual/en/reserved.classes.php)
// Imprime: object(stdClass)#1 (1) { ["foo"]=> string(3) "bar" }
$objeto_indefinido->foo='bar';
var_dump($objeto_indefinido);
?>Depender del valor predeterminado de una variable sin inicializar es problemático al incluir un archivo en otro que use el mismo nombre de variable. Un error de nivelE_NOTICEes emitido cuendo se trabaja con variables sin inicializar, con la excepción del caso en el que se anexan elementos a un array no inicializado. La construcción del lenguajeisset()puede ser usada para detectar si una variable ya ha sido inicializada.
PHP proporciona una gran cantidad de variables predefinidas a cualquier script que se ejecute. Muchas de éstas, sin embargo, no pueden ser completamente documentadas ya que dependen del servidor que esté corriendo, la versión y configuración de dicho servidor, y otros factores. Algunas de estas variables no estarán disponibles cuando se ejecute PHP desde lalínea de comandos. Para obtener una lista de estas variables, por favor vea la sección sobreVariables Predefinidas Reservadas.
PHP ofrece un conjunto adicional de arrays predefinidas que contienen variables del servidor web, el entorno y entradas del usuario. Estos nuevos arrays son un poco especiales porque son automáticamente globales. Por esta razón, son conocidas a menudo como "superglobales". Las superglobales se mencionan más abajo; sin embargo para una lista de sus contenidos y más información sobre variables predefinidas en PHP, por favor consulte la secciónVariables predefinidas reservadas. Asimismo, podrá notar cómo las antiguas variables predefinidas ($HTTP_*_VARS) todavía existen.
Nota:Variables variables
Las superglobales no pueden ser usadas comovariables variablesal interior de funciones o métodos de clase.
Nota:
Aún cuando las superglobales y
HTTP_*_VARSpueden existir al mismo tiempo; estas variables no son idénticas, así que modificar una no cambia la otra.
Si ciertas variables no son definidas envariables_order, los arrays de PHP predefinidos asociados a estas, estarán vacíos.
El ámbito de una variable es el contexto dentro del que la variable está definida. La mayor parte de las variables PHP sólo tienen un ámbito simple. Este ámbito simple también abarca los ficheros incluídos y los requeridos. Por ejemplo:
<?php
$a=1;
include'b.inc';
?>Aquí, la variable$aestará disponible al interior del script incluidob.inc. Sin embargo, al interior de las funciones definidas por el usuario se introduce un ámbito local a la función. Cualquier variable usada dentro de una función está, por omisión, limitada al ámbito local de la función. Por ejemplo:
<?php
$a=1;/* ámbito global */
functiontest()
{
echo$a;/* referencia a una variable del ámbito local */
}
test();
?>Este script no producirá salida, ya que la sentencia echo utiliza una versión local de la variable$a, a la que no se ha asignado ningún valor en su ámbito. Puede que usted note que hay una pequeña diferencia con el lenguaje C, en el que las variables globales están disponibles automáticamente dentro de la función a menos que sean expresamente sobreescritas por una definición local. Esto puede causar algunos problemas, ya que la gente puede cambiar variables globales inadvertidamente. En PHP, las variables globales deben ser declaradas globales dentro de la función si van a ser utilizadas dentro de dicha función.
globalEn primer lugar, un ejemplo de uso deglobal:
Ejemplo #1 Uso deglobal
<?php
$a=1;
$b=2;
functionSuma()
{
global$a,$b;
$b=$a+$b;
}
Suma();
echo$b;
?>El script anterior producirá la salida3. Al declarar$ay$bglobales dentro de la función, todas las referencias a tales variables se referirán a la versión global. No hay límite al número de variables globales que se pueden manipular dentro de una función.
Un segundo método para acceder a las variables desde un ámbito global es usando el array$GLOBALS. El ejemplo anterior se puede reescribir así:
Ejemplo #2 Uso de$GLOBALSen lugar de global
<?php
$a=1;
$b=2;
functionSuma()
{
$GLOBALS['b'] =$GLOBALS['a'] +$GLOBALS['b'];
}
Suma();
echo$b;
?>El array$GLOBALSes un array asociativo con el nombre de la variable global como clave y los contenidos de dicha variable como el valor del elemento del array.$GLOBALSexiste en cualquier ámbito, esto ocurre ya que$GLOBALSes unasuperglobal. Aquí hay un ejemplo que demuestra el poder de las superglobales:
Ejemplo #3 Ejemplo que demuestra las superglobales y el ámbito
<?php
functiontest_global()
{
// La mayoría de variables predefinidas no son "super" y requieren
// 'global' para estar disponibles al ámbito local de las funciones.
global$HTTP_POST_VARS;
echo$HTTP_POST_VARS['name'];
// Las superglobales están disponibles en cualquier ámbito y no
// requieren 'global'. Las superglobales están disponibles desde
// PHP 4.1.0, y ahora HTTP_POST_VARS se considera obsoleta.
echo$_POST['name'];
}
?>Nota:
Utilizar una clave
globalfuera de una función no es un error. Esta puede ser utilizada aún si el fichero está incluido desde el interior de una función.
staticOtra característica importante del ámbito de las variables es la variableestática. Una variable estática existe sólo en el ámbito local de la función, pero no pierde su valor cuando la ejecución del programa abandona este ámbito. Consideremos el siguiente ejemplo:
Ejemplo #4 Ejemplo que demuestra la necesidad de variables estáticas
<?php
functiontest()
{
$a=0;
echo$a;
$a++;
}
?>Esta función tiene poca utilidad ya que cada vez que es llamada asigna a$ael valor0e imprime un0. La sentencia$a++, que incrementa la variable, no sirve para nada, ya que en cuanto la función finaliza, la variable$adesaparece. Para hacer una función útil para contar, que no pierda la pista del valor actual del conteo, la variable$adebe declararse como estática:
Ejemplo #5 Ejemplo del uso de variables estáticas
<?php
functiontest()
{
static$a=0;
echo$a;
$a++;
}
?>Ahora,$ase inicializa únicamente en la primera llamada a la función, y cada vez que la funcióntest()es llamada, imprimirá el valor de$ay lo incrementa.
Las variables estáticas también proporcionan una forma de manejar funciones recursivas. Una función recursiva es la que se llama a sí misma. Se debe tener cuidado al escribir una función recursiva, ya que puede ocurrir que se llame a sí misma indefinidamente. Hay que asegurarse de implementar una forma adecuada de terminar la recursión. La siguiente función cuenta recursivamente hasta 10, usando la variable estática$countpara saber cuándo parar:
Ejemplo #6 Variables estáticas con funciones recursivas
<?php
functiontest()
{
static$count=0;
$count++;
echo$count;
if ($count<10) {
test();
}
$count--;
}
?>Nota:
Las variables estáticas pueden ser declaradas como se ha visto en los ejemplos anteriores. Desde PHP 5.6 se pueden asignar valores a estas variables que sean el resultado de expresiones, aunque no se pueden usar funciones aquí, lo cual causaría un eror de análisis.
Ejemplo #7 Declaración de variables estáticas
<?php
functionfoo(){
static$int=0;// correcto
static$int=1+2;// correcto (a partir de PHP 5.6)
static$int=sqrt(121);// incorrecto (ya que es una función)
$int++;
echo$int;
}
?>
Nota:
Las declaraciones estáticas son resueltas en tiempo de compilación.
globalystaticEl motor Zend 1, utilizado por PHP 4, implementa los modificadoresstaticyglobalpara variables en términos dereferencias. Por ejemplo, una variable global verdadera importada dentro del ámbito de una función conglobalcrea una referencia a la variable global. Esto puede ser causa de un comportamiento inesperado, tal y como podemos comprobar en el siguiente ejemplo:
<?php
functionprueba_referencia_global() {
global$obj;
$obj= &newstdclass;
}
functionprueba_no_referencia_global() {
global$obj;
$obj= newstdclass;
}
prueba_referencia_global();
var_dump($obj);
prueba_no_referencia_global();
var_dump($obj);
?>El resultado del ejemplo sería:
Un comportamiento similar se aplica astatic. Las referencias no son almacenadas estáticamente.
<?php
function &obtener_instancia_ref() {
static$obj;
echo'Objeto estático: ';
var_dump($obj);
if (!isset($obj)) {
// Asignar una referencia a la variable estática
$obj= &newstdclass;
}
$obj->property++;
return$obj;
}
function &obtener_instancia_no_ref() {
static$obj;
echo'Objeto estático: ';
var_dump($obj);
if (!isset($obj)) {
// Asignar el objeto a la variable estática
$obj= newstdclass;
}
$obj->property++;
return$obj;
}
$obj1=obtener_instancia_ref();
$aun_obj1=obtener_instancia_ref();
echo"\n";
$obj2=obtener_instancia_no_ref();
$aun_obj2=obtener_instancia_no_ref();
?>El resultado del ejemplo sería:
Este ejemplo demuestra que al asignar una referencia a una variable estática, esta no esrecordadacuando se invoca la funcion&obtener_instancia_ref()por segunda vez.
A veces es conveniente tener nombres de variables variables. Dicho de otro modo, son nombres de variables que se pueden definir y usar dinámicamente. Una variable normal se establece con una sentencia como:
<?php
$a='hola';
?>Una variable variable toma el valor de una variable y lo trata como el nombre de una variable. En el ejemplo anterior,hola, se puede usar como el nombre de una variable utilizando dos signos de dólar. Es decir:
<?php
$$a='mundo';
?>En este momento se han definido y almacenado dos variables en el árbol de símbolos de PHP:$a, que contiene "hola", y$hola, que contiene "mundo". Es más, esta sentencia:
<?php
echo"$a${$a}";
?>produce el mismo resultado que:
<?php
echo"$a$hola";
?>esto quiere decir que ambas producen el resultado:hola mundo.
Para usar variables variables con arrays hay que resolver un problema de ambigüedad. Si se escribe$$a[1], el intérprete necesita saber si nos referimos a utilizar$a[1]como una variable, o si se pretendía utilizar$$acomo variable y el índice [1] como índice de dicha variable. La sintaxis para resolver esta ambigüedad es:${$a[1]}para el primer caso y${$a}[1]para el segundo.
También se puede acceder a las propiedades de una clase usando el nombre de propiedad variable. Este será resuelto dentro del ámbito del cual se hizo la llamada. Por ejemplo, en la expresión$foo->$bar, se buscará$baren el ámibto local y se empleará su valor será como el nombre de la propiedad de$foo. Esto también es cierto si$bares un acceso a un array.
Además, derreferenciar una propiedad variable que es un array tiene diferente semántica entre PHP 5 y PHP 7. Laguías de migración de PHP 7.0incluye más detalles sobre los tipos de expresiones que han cambiado, y cómo colocar llaves para evitar ambigüedades.
También se pueden usar llaves para delimitar de forma clara el nombre de la propiedad. Son muy útila al acceder a valores dentro una propiedad que contiene un array, cuando el nombre de la propiedad está compuesto de múltiples partes, o cuando el nombre de la propiedad contiene caracteres que de otro modo no son válidos (p.ej. desdejson_decode()oSimpleXML).
Ejemplo #1 Ejemplo de propiedad variable
<?php
classfoo{
var$bar='Soy bar.';
var$arr= array('Soy A.','Soy B.','Soy C.');
var$r='Soy r.';
}
$foo= newfoo();
$bar='bar';
$baz= array('foo','bar','baz','quux');
echo$foo->$bar."\n";
echo$foo->{$baz[1]} ."\n";
$start='b';
$end='ar';
echo$foo->{$start.$end} ."\n";
$arr='arr';
echo$foo->$arr[1] ."\n";
echo$foo->{$arr[1]} ."\n";
?>El resultado del ejemplo sería:
Por favor tenga en cuenta que las variables variables no pueden usarse con losArrays superglobalesde PHP al interior de funciones o métodos de clase. La variable$thises también una variable especial que no puede ser referenciada dinámicamente.
Cuando se envía un formulario a un script de PHP, la información de dicho formulario pasa a estar automáticamente disponible en el script. Existen algunas formas de acceder a esta información, por ejemplo:
Ejemplo #1 Un formulario HTML sencillo
<form action="foo.php" method="post">
Nombre usuario: <input type="text" name="username" /><br />
Email: <input type="text" name="email" /><br />
<input type="submit" name="submit" value="¡Enviarme!" />
</form>A partir de PHP 5.4.0, solamente existen dos maneras de acceder a datos desde formularios HTML. Los métodos disponibles actualmente se enumeran a continuación:
Ejemplo #2 Acceso a datos de un formulario HTML sencillo con POST
<?php echo $_POST['username']; echo $_REQUEST['username']; ?>
Habían otras formas de acceder a la entrada del usuario en versiones antiguas de PHP. Están enumeradas abajo. Véase el historial de cambios al final para más detalles.
Ejemplo #3 Old methods of accessing user input
<?php
// OJO: estos métodos ya NO ESTÁN soportados.
// Los válidos están descritos arriba.
// Usar import_request_variables() - esta función ha sido eliminada en PHP 5.4.0
import_request_variables('p','p_');
echo$p_username;
// Estas variables predefinidas fueron eliminadas en PHP 5.4.0
echo$HTTP_POST_VARS['username'];
// Usar register_globals. Esta característica fue eliminada en PHP 5.4.0
echo$username;
?>Usar un formulario con GET es similar excepto en el uso de variables predefinidas, que en este caso serán del tipo GET. GET también se usa conQUERY_STRING(la información despues del símbolo '?' en una URL). Por ejemplohttp://www.example.com/test.php?id=3contiene datos GET que son accesibles con$_GET['id']. Véase también$_REQUEST.
Nota:
Puntos y espacios en nombres de variables son convertidos a guiones bajos. Por ejemplo
<input name="a.b" />se convierte en$_REQUEST["a_b"].
PHP también entiende arrays en el contexto de variables de formularios (vea lafaq relacionada). Se puede, por ejemplo, agrupar juntas variables relacionadas o usar esta característica para obtener valores de una entrada "select" múltiple. Por ejemplo, vamos a mandar un formulario a sí mismo y a presentar los datos cuando se reciban:
Ejemplo #4 Variables de formulario más complejas
<?php
if ($_POST) {
echo'<pre>';
echohtmlspecialchars(print_r($_POST,true));
echo'</pre>';
}
?>
<form action="" method="post">
Nombre: <input type="text" name="personal[nombre]" /><br />
Email: <input type="text" name="personal[email]" /><br />
Cerveza: <br />
<select multiple name="cerveza[]">
<option value="warthog">Warthog</option>
<option value="guinness">Guinness</option>
<option value="stuttgarter">Stuttgarter Schwabenbräu</option>
</select><br />
<input type="submit" value="¡enviarme!" />
</form>Cuando se envía un formulario, es posible usar una imagen en vez del botón estándar "submit":
<input type="image" src="image.gif" name="sub" />
Cuando el usuario hace click en cualquier parte de la imagen, el formulario que la acompaña se transmitirá al servidor con dos variables adicionales,sub_xysub_y. Éstas contienen las coordenadas del clic del usuario dentro de la imagen. Los más experimentados puede notar que los nombres de variable enviados por el navegador contienen un guión en vez de un subrayado (guión bajo), pero PHP convierte el guión en subrayado automáticamente.
PHP soporta cookies de HTTP de forma transparente tal y como están definidas en» RFC 6265. Las cookies son un mecanismo para almacenar datos en el navegador y así rastrear o identificar a usuarios que vuelven. Se pueden crear cookies usando la funciónsetcookie(). Las cookies son parte de la cabecera HTTP, así que se debe llamar a la función SetCookie antes de que se envíe cualquier salida al navegador. Es la misma restricción que para la funciónheader(). Los datos de una cookie están disponibles en el array de datos de la cookies apropiada, tal como$_COOKIEy$_REQUEST. Véase la página desetcookie()del manual para más detalles y ejemplos.
Si se quieren asignar múltiples valores a una sola cookie, basta con asignarlo como un array. Por ejemplo:
<?php
setcookie("MiCookie[foo]",'Prueba 1',time()+3600);
setcookie("MiCookie[bar]",'Prueba 2',time()+3600);
?>Esto creará dos cookies separadas aunqueMiCookieserá un array simple en el script. Si se quiere definir una sola cookie con valores múltiples, considere el uso de la funciónserialize()oexplode()primero en el valor.
Nótese que una cookie reemplazará a una cookie anterior que tuviese el mismo nombre en el navegador a menos que la ruta o el dominio fuesen diferentes. Así, para una aplicación de carrito de compras se podría querer mantener un contador e ir pasándolo. Es decir:
Ejemplo #5 Un ejemplo desetcookie()
<?php
if (isset($_COOKIE['conteo'])) {
$conteo=$_COOKIE['conteo'] +1;
} else {
$conteo=1;
}
setcookie('conteo',$conteo,time()+3600);
setcookie("Carrito[$conteo]",$item,time()+3600);
?>Típicamente, PHP no altera los nombres de las variables cuando se pasan a un script. Sin embargo, hay que notar que el punto no es un carácter válido en el nombre de una variable PHP. Para conocer la razón, considere el siguiente ejemplo:
<?php
$varname.ext;/* nombre de variable inválido */
?>Por esta razón, es importante hacer notar que PHP reemplazará automáticamente cualquier punto en los nombres de variables de entrada por guiones bajos (subrayados).
Dado que PHP determina los tipos de las variables y los convierte (generalmente) según lo que necesita, no siempre resulta obvio de qué tipo es una variable dada en un momento concreto. PHP incluye varias funciones que descubren de qué tipo es una variable:gettype(),is_array(),is_float(),is_int(),is_object(), yis_string(). Vea también el capítulo sobreTipos.
| Versión | Descripción |
|---|---|
| 7.2.34, 7.3.23, 7.4.11 | Losnombresde las cookies entrantes ya no son con url-decoded por razones de seguridad. |
Una constante es un identificador (nombre) para un valor simple. Como el nombre sugiere, este valor no puede variar durante la ejecución del script (a excepción de lasconstantes mágicas, que en realidad no son constantes). Por defecto, una constante distingue mayúsculas y minúsculas. Por convención, los identificadores de constantes siempre se declaran en mayúsculas.
El nombre de una constante sigue las mismas reglas que cualquier otra etiqueta de PHP. Un nombre de constante válido empieza por una letra o guion bajo, seguido por cualquier número de letras, números o guiones bajos. Usando una expresión regular, se representaría de la siguiente manera:[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
Vea tambiénGuía de entorno de usuario para nombres.
Ejemplo #1 Nombres de constantes correctos e incorrectos
<?php
// Nombres de constantes correctos
define("FOO","something");
define("FOO2","something else");
define("FOO_BAR","something more");
// Nombres de constantes incorrectos
define("2FOO","something");
// Esto es válido, pero debe evitarse:
// PHP podría cualquier día proporcionar una constante mágica
// que rompiera el script
define("__FOO__","something");
?>Nota:Para nuestros propósitos, una letra está entre los carácteres a-z, A-Z, y los caracteres ASCII del 127 hasta el 255 (0x7f-0xff).
Igual que lassuperglobals, el acceso a una constante es global. Se puede acceder a constantes desde cualquier sitio del script sin importar desde donde. Para más información en el acceso, lea el manual en la secciónacceso a variables.
Se puede definir una constante usando la funcióndefine()o con la palabra reservadaconstfuera de la definición de una clase a partir PHP 5.3.0. Mientras quedefine()permite definir una constante con una expresión arbitraria, la palabra reservadaconsttiene retricciones que se resumen en el siguiente párrafo. Una vez que la constante está definida, no puede ser cambiada o redifinida.
Antes de PHP 5.6, al emplear la palabra reservadaconst, solamente los datos escalares (boolean,integer,floatystring) pueder estar contenidos en constante. Desde PHP 5.6 en adelante, es posible definir una constante como una expresión escalar, y también es posible definir unarrayconstante. Es posible definir constantes como unresource, pero debería evitarse, ya que podría ocasionar resultados inesperados.
Para obtener el valor de una constante solo es necesario especificar su nombre. A diferencia de las variables,nose debe prefijar una constante con el signo$. También se puede usar la funciónconstant()para leer el valor de una constante si se desea obtener el valor de una constante de forma dinámica. Useget_defined_constants()para obtener una lista de todas las constantes definidas.
Nota:Las contantes y las variables (globales) se encuentran en un espacio de nombres distinto. Esto implica que por ejemplo
truey$TRUEson diferentes.
Si se usa una constante que todavía no está definida, PHP asume que se está refiriendo al nombre de la constante en si, igual que si fuera unastring(CONSTANT vs "CONSTANT"). Cuando esto suceda, se mostrará un error de nivelE_NOTICE. Ver también la sección en el manual de porqué$foo[bar]es incorrecto (a no ser que primerodefine()barcomo constante). Esto no se aplica a lasconstantes (completamente) cualificadas, lo cual emitirá un error fatal si no está definida. Si simplemente quiere comprobar si una constante está definida, use la funcióndefined().
Estas son las diferencias entre constantes y variables:
$), como prefijo.const, y, a partir de PHP 7, las constantes de array también se pueden definir condefine(). Se pueden utilizar arrays en expresiones escalares constantes (por ejemplo,const FOO = array(1,2,3)[0];), aunque el resultado final debe ser un valor de un tipo permitido.Ejemplo #1 Definición de constantes
<?php
define("CONSTANTE","Hola mundo.");
echoCONSTANTE;// muestra "Hola mundo."
echoConstante;// muestra "Constant" y se emite un aviso.
?>Ejemplo #2 Definición de constantes usando el la palabra reservadaconst
<?php
// Funciona a partir de PHP 5.3.0
constCONSTANTE='Hola Mundo';
echoCONSTANTE;
// Funciona a partir de PHP 5.6.0
constOTRA_CONSTANTE=CONSTANTE.'; Adiós Mundo';
echoOTRA_CONSTANTE;
constANIMALES= array('perro','gato','pájaro');
echoANIMALES[1];// muestra "gato"
// Funciona a partir de PHP 7
define('ANIMALES', array(
'perro',
'gato',
'pájaro'
));
echoANIMALES[1];// muestra "gato"
?>Nota:
A diferencia de definir constantes usandodefine(), las constantes definidas con la palabra clave
constdeben declararse en el nivel superior del entorno de la aplicación porque se definen en tiempo de ejecución. Esto significa que no pueden declararse dentro de funciones, bucles, sentenciasifo bloquestry/catch.
Vea tambiénConstantes de clase.
PHP ofrece un gran número deconstantes predefinidasa cualquier script en ejecucción. Muchas de estas constantes, sin embargo, son creadas por diferentes extensiones, y sólo estarán presentes si dichas extensiones están disponibles, bien por carga dinámica o porque han sido compiladas.
Hay nueve constantes mágicas que cambian dependiendo de dónde se emplean. Por ejemplo, el valor de__LINE__depende de la línea en que se use en el script. Todas estas constantes «mágicas» se resuelven durante la compilación, a diferencia de las constantes normales que lo hacen durante la ejecución. Estas constantes especiales son sensibles a mayúsculas Estas constantes especiales distinguen mayúsculas y minúsculas, y son las siguientes:
| Nombre | Descripción |
|---|---|
__LINE__ | El número de línea actual en el fichero. |
__FILE__ | Ruta completa y nombre del fichero con enlaces simbólicos resueltos. Si se usa dentro de un include, devolverá el nombre del fichero incluido. |
__DIR__ | Directorio del fichero. Si se utiliza dentro de un include, devolverá el directorio del fichero incluído. Esta constante es igual quedirname(__FILE__). El nombre del directorio no lleva la barra final a no ser que esté en el directorio root. |
__FUNCTION__ | Nombre de la función. |
__CLASS__ | Nombre de la clase. El nombre de la clase incluye el namespace declarado en (p.e.j.Foo\Bar). Tenga en cuenta que a partir de PHP 5.4 __CLASS__ también funciona con traits. Cuando es usado en un método trait, __CLASS__ es el nombre de la clase del trait que está siendo utilizado. |
__TRAIT__ | El nombre del trait. El nombre del trait incluye el espacio de nombres en el que fue declarado (p.e.j.Foo\Bar). |
__METHOD__ | Nombre del método de la clase. |
__NAMESPACE__ | Nombre del espacio de nombres actual. |
ClassName::class | El nombre de clase completamente cualificado. Véase también::class. |
Véase tambiénget_class(),get_object_vars(),file_exists()yfunction_exists().
| Versión | Descripción |
|---|---|
| 5.5.0 | Se añadió la constante mágica::class |
| 5.4.0 | Se añadió la constante__TRAIT__ |
| 5.3.0 | Se añadieron las constantes__DIR__y__NAMESPACE__ |
| 5.0.0 | Se añadió la constante__METHOD__ |
| 5.0.0 | Antes de esta versión, los valores de algunas constantes mágicas estaban siempre en minúsculas. Ahora todas ellas están en mayúsculas (contienen nombres mientras eran declaradas). |
| 4.3.0 | Se añadieron las constantes__FUNCTION__y__CLASS__ |
| 4.0.2 | __FILE__siempre contiene una ruta absoluta con enlaces simbólicos resueltos, mientras que en versiones antiguas contenía una ruta relativa bajo algunas circunstancias |
La expresiones son los bloques de construcción más importantes de PHP. En PHP casi todo lo que se escribe es una expresión. La manera más simple y acertada de definir lo que es una expresión es «cualquier cosa que tiene un valor».
Las formas más básicas de expresiones son las constantes y las variables. Cuando se escribe "$a= 5", se está asignando '5' a$a. '5', obviamente, tiene el valor 5, o en otras palabras, '5' es una expresión con el valor de 5 (en este caso, '5' es una constante entera).
Después de esta asignación, se espera que el valor de$asea 5 también, por lo que si se escribe$b=$a, se espera que esto se comporte tal como si se escribiera$b= 5. En otras palabras,$aes también una expresión con el valor 5. Si todo funciona bien, esto es exactamente lo que sucederá.
Un ejemplo de expresiones algo más complejo son las funciones. Por ejemplo, considere la siguiente función:
<?php
functionfoo()
{
return5;
}
?>Asumiendo que está familiarizado con el concepto de función (si no lo está, échele una ojeada al capítulo sobrefunciones), asumirá que escribir$c = foo()es esencialmente igual que escribir$c = 5. Y está en lo cierto. Las funciones son expresiones con el valor de sus valores devueltos. Ya quefoo()devuelve 5, el valor de la expresión 'foo()' es 5. Normalmente las funciones no sólo devuelven un valor estático, sino que computan algo.
Por supuesto, los valores en PHP no tienen que ser enteros, y con frecuencia no lo son. PHP soporta cuatro tipos de valores escalares: valores enteros (integer), valores de coma (punto) flotante (float), valores de cadena (string) y valores booleanos (boolean) - (valores escalares son aquellos que no se pueden descomponer en piezas más pequeñas, a diferencia de las matrices, por ejemplo). PHP también soporta dos tipos compuestos (no escalares): matrices (arrays) y objetos. Cada uno de estos tipos de valores pueden ser asignados a variables o devueltos desde funciones.
PHP lleva las expresiones mucho más allá, de la misma manera que lo hacen otros lenguajes. PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una expresión. Considere el ejemplo que ya hemos tratado, '$a= 5'. Es fácil de ver que aquí hay dos valores involucrados, el valor de la constante entera '5', y el valor de$aque ha sido actualizado a 5 también. Aunque la verdad es que existe aquí un valor adicional involucrado, que es el valor de la asignación misma. La asignación evalúa al valor asignado, en este caso 5. En la práctica, esto significa que '$a= 5', sin importar lo que haga, es una expresión con el valor 5. De este modo, escribir algo como '$b= ($a= 5)' es igual que escribir '$a= 5;$b= 5;' (el punto y coma marca el final de una sentencia). Ya que las asignaciones se analizan de derecha a izquierda, también se puede escribir '$b=$a= 5'.
Otro buen ejemplo de orientación a expresiones es el pre- y post-incremento y decremento. Los usuarios de PHP y de otros muchos lenguajes pueden estar familiarizados con la notaciónvariable++yvariable--. Éstos son losoperadores de incremento y decremento. En PHP, al igual que en C, hay dos tipos de incrementos - pre-incremento y post-incremento. Ambos esencialmente incrementan la variable, y el efecto sobre la variable es idéntico. La diferencia está con el valor de la expresión de incremento. Pre-incremento, que se escribre '++$variable', evalúa al valor incrementado (PHP incrementa la variable antes de leer su valor, de ahí el nombre de 'pre-incremento'). Post-incremento, que se escribe '$variable++' evalúa el valor original de $variable, antes de que sea incrementado (PHP incrementa la variable después de leer su valor, de ahí el nombre de 'post-incremento').
Un tipo de expresiones muy comunes son las expresiones decomparación. Estas expresiones evalúan si algo esfalse(falso) otrue(verdadero). PHP soporta > (mayor que), >= (mayor o igual que), == (igual), != (distinto), < (menor que) y <= (menor o igual que). El lenguaje también soporta un conjunto de operadores de equivalencia estricta: === (igual y del mismo tipo) y !== (diferente o de distinto tipo). Estas expresiones se usan mayormente dentro de ejecuciones condicionales, tales como la sentenciaif.
El último ejemplo de expresiones que trataremos aquí es una combinación de expresiones operador-asignación. Ya sabe que si quiere incrementar$aen 1, puede simplemente escribir '$a++' o '++$a'. Pero si lo que quiere es añadirle más de uno, por ejemplo 3, podría escribir '$a++' varias veces, pero esto, obviamente, no es una manera muy eficiente o cómoda. Una práctica mucho más común es escribir '$a=$a+ 3'. '$a+ 3' evalúa al valor de$amás 3, y se vuelve a asignar a$a, lo que resulta en incrementar$aen 3. En PHP, como en otros lenguajes como C, se puede escribir esto de una manera más abreviada, lo que con el tiempo se podría convertir en una forma más clara y rápida de entenderlo. Añadir 3 al valor actual de$apuede ser escrito '$a+= 3'. Esto significa exactamente "toma el valor de$a, añádele 3 y asígnalo de nuevo a$a". Además de ser más corto y claro, también resulta en una ejecución más rápida. El valor de '$a+= 3', al igual que el valor de una asignación normal, es el valor asignado. Observe que NO es 3, sino el valor combinado de$amás 3 (éste es el valor que es asignado a$a). Se puede usar cualquier operador compuesto de dos partes en este modo de operador-asignación, por ejemplo '$a-= 5' (restar 5 del valor de$a), '$b*= 7' (multiplicar el valor de$bpor 7), etc.
Existe una expresión más que le puede parecer rara si no la ha visto en otros lenguajes, el operador condicional ternario:
<?php
$primero?$segundo:$tercero
?>Si el valor de la primera subexpresión estrue(no es cero), se evalúa la segunda subexpresión, y ése será el resultado de la expresión condicional. Si no, se evalúa la tercera subexpresión, y ése será el valor.
El siguiente ejemplo debería ayudarle a comprender un poco mejor el pre- y post-incremento y las expresiones en general:
<?php
functiondoble($i)
{
return$i*2;
}
$b=$a=5;/* asignar el valor cinco a la variable $a y $b */
$c=$a++;/* post-incremento, asignar el valor original de $a
(5) a $c */
$e=$d= ++$b;/* pre-incremento, asignar el valor incrementado de
$b (6) a $d y $e */
/* en este punto, $d y $e son iguales a 6 */
$f=doble($d++);/* asignar el doble del valor de $d antes
del incremento, 2*6 = 12, a $f */
$g=doble(++$e);/* asignar el doble del valor de $e después
del incremento, 2*7 = 14, a $g */
$h=$g+=10;/* primero, $g es incrementado en 10 y finaliza con el
valor 24. El valor de la asignación (24) es
asignado después a $h, y $h finaliza también con el
valor 24. */
?>Algunas expresiones pueden considerarse como sentencias. En este caso, una sentencia tiene la forma 'expr ;', es decir, una expresión seguida de un punto y coma. En'$b = $a = 5;','$a = 5'es una expresión válida, pero no es una sentencia en sí. Sin embargo,'$b = $a = 5;'es una sentencia válida.
Lo último que vale la pena mencionar es el valor verdadero de las expresiones. En muchos casos, principalmente en ejecuciones condicionales y bucles, no interesa saber el valor específico de la expresión, sino sólo si el valor significatrueofalse. Las constantestrueyfalse(insensible a mayúsculas-minúsculas) son los dos valores booleanos posibles. Cuando es necesario, una expresión es convertida automáticamente al tipo boolean. Véase lasección sobre conversión de tipospara más detalles.
PHP proporciona una implementación completa y potente de expresiones, y documentarla por completo va más allá del ámbito de este manual. Los ejemplos de arriba deberían darle una buena idea de lo que son las expresiones y cómo construir expresiones útiles. Durante el resto de este manual se escribiráexprpara indicar cualquier expresión de PHP válida.
Un operador es algo que toma uno más valores (o expresiones, en la jerga de programación) y produce otro valor (de modo que la construcción en si misma se convierte en una expresión).
Los operadores se pueden agrupar de acuerdo con el número de valores que toman. Los operadores unarios toman sólo un valor, por ejemplo!(eloperador lógico de negación) o++(eloperador de incremento). Los operadores binarios toman dos valores, como los familiaresoperadores aritméticos+(suma) y-(resta), y la mayoría de los operadores de PHP entran en esta categoría. Finalmente, hay sólo unoperador ternario,? :, el cual toma tres valores; usualmente a este se le refiere simplemente como "el operador ternario" (aunque podría tal vez llamarse más correctamente como el operador condicional).
Una lista completa de operadores de PHP sigue en la secciónPrecedencia de Operadores. La sección también explica la precedencia y asociatividad de los operadores, las cuales gobiernan exactamente cómo son evaluadas expresiones que contienen varios diferentes operadores.
La precedencia de un operador indica qué tan "estrechamente" se unen dos expresiones juntas. Por ejemplo, en la expresión1 + 5 * 3, la respuesta es16y no18porque el operador de multiplicación ("*") tiene una precedencia mayor que el operador de adición ("+"). Los paréntesis pueden ser usados para forzar la precedencia, si es necesario. Por ejemplo:(1 + 5) * 3se evalúa como18.
Cuando los operadores tienen igual precedencia su asociatividad decide cómo se agrupan. Por ejemplo "-" tiene asociatividad a izquierda, así1 - 2 - 3se agrupa como(1 - 2) - 3y se evalúa a-4. "=", por otra parte, tiene asociatividad a derecha, así$a = $b = $cse agrupa como$a = ($b = $c).
Los operadores de igual precedencia que no son asociativos no pueden usarse unos junto a otros, por ejemplo,1 < 2 > 1es ilegal en PHP. La expresión1 <= 1 == 1, por otro lado, es legal, ya que el operador==tiene menos precedencia que el operador<=.
El uso de paréntesis, incluso cuando no es estrictamente necesario, a menudo puede aumentar la legibilidad del código haciendo grupos explícitamente en lugar de confiar en la precedencia y asociatividad implícitas del operador.
La siguiente tabla enumera los operadores en orden de precedencia, con los de más alta precedencia al inicio. Los operadores en la misma línea tienen igual precedencia, en cuyo caso la asociatividad decide el agrupamiento.
| Asociatividad | Operadores | Información adicional |
|---|---|---|
| no asociativo | clonenew | cloneandnew |
| izquierda | [ | array() |
| derecha | ** | aritmética |
| derecha | ++--~(int)(float)(string)(array)(object)(bool)@ | tiposeincremento/decremento |
| no asociativo | instanceof | tipos |
| derecha | ! | lógico |
| izquierda | */% | aritmética |
| izquierda | +-. | aritméticaystring |
| izquierda | <<>> | bit a bit |
| no asociativo | <<=>>= | comparación |
| no asociativo | ==!====!==<><=> | comparación |
| izquierda | & | bit a bityreferencias |
| izquierda | ^ | bit a bit |
| izquierda | | | bit a bit |
| izquierda | && | lógico |
| izquierda | || | lógico |
| derecha | ?? | comparación |
| izquierda | ? : | ternario |
| derecha | =+=-=*=**=/=.=%=&=|=^=<<=>>= | asignación |
| izquierda | and | lógico |
| izquierda | xor | lógico |
| izquierda | or | lógico |
Ejemplo #1 Asociatividad
<?php
$a=3*3%5;// (3 * 3) % 5 = 4
// la asociatividad del operador ternario difiere de C/C++
$a=true?0:true?1:2;// (true ? 0 : true) ? 1 : 2 = 2
$a=1;
$b=2;
$a=$b+=3;// $a = ($b += 3) -> $a = 5, $b = 5
?>La precedencia y asociatividad de los operadores solamente determinan cómo se agrupan las expresiones, no especifican un orden de evaluación. PHP no especifica (en general) el orden en que se evalúa una expresión y se debería evitar el código que se asume un orden específico de evaluación, ya que el comportamiento puede cambiar entre versiones de PHP o dependiendo de código circundante.
Ejemplo #2 Orden de evaluación no definido
<?php
$a=1;
echo$a+$a++;// podría mostrar 2 o 3
$i=1;
$array[$i] =$i++;// podría establecer el índice a 1 o 2
?>Ejemplo #3+,-y.tienen la misma precedencia
<?php
$x=4;
// esta línea podría resultar en una salida inesperada:
echo"x menos uno igual a ".$x-1.", o eso espero\n";
// ya que se evalúa como esta línea:
echo (("x menos uno igual a ".$x) -1) .", o eso espero\n";
// la precedencia deseada se puede forzar con paréntesis:
echo"x menos uno igual a ". ($x-1) .", o eso espero\n";
?>El resultado del ejemplo sería:
-1, o eso espero -1, o eso espero x menos uno igual a 3, o eso espero
Nota:
Aunque
=tiene una precedencia menor que la mayoría de los demás operadores, PHP aun permitirá expresiones similares a lo siguiente:if (!$a = foo()), en cuyo caso el valor devuelto defoo()es puesto en$a.
¿Recuerda la aritmética básica de la escuela? Estos funcionan igual que aquellos.
| Ejemplo | Nombre | Resultado |
|---|---|---|
| +$a | Identidad | Conversión de$aaintofloatsegún el caso. |
| -$a | Negación | Opuesto de$a. |
| $a + $b | Adición | Suma de$ay$b. |
| $a - $b | Sustracción | Diferencia de$ay$b. |
| $a * $b | Multiplicación | Producto de$ay$b. |
| $a / $b | División | Cociente de$ay$b. |
| $a % $b | Módulo | Resto de$adividido por$b. |
| $a ** $b | Exponenciación | Resultado de elevar$aa la potencia$bésima. Introducido en PHP 5.6. |
El operador de división ("/") devuelve un valor flotante a menos que los dos operandos sean integers (o strings que se conviertan a integers) y los números sean divisibles, en cuyo caso será devuelto un valor integer.
Los operandos del módulo se convierten en integers (por extracción de la parte decimal) antes del procesamiento.
El resultado del operador módulo%tiene el mismo signo que el dividendo — es decir, el resultado de$a % $btendrá el mismo signo que$a. Por ejemplo:
<?php
echo (5%3)."\n";// muestra 2
echo (5% -3)."\n";// muestra 2
echo (-5%3)."\n";// muestra -2
echo (-5% -3)."\n";// muestra -2
?>Véase también la página del manual sobrefunciones matemáticas.
El operador básico de asignación es "=". Se podría inclinar a pensar primero que es como un "igual a". No lo es. Realmente significa que el operando de la izquierda se establece con el valor de la expresión de la derecha (es decir, "se define como").
El valor de una expresión de asignación es el valor asignado. Es decir, el valor de "$a = 3" es de 3. Esto permite hacer algunas cosas intrincadas:
<?php
$a= ($b=4) +5;// ahora $a es igual a 9 y $b se ha establecido en 4.
?>Además del operador básico de asignación, existen «operadores combinados» para todos los dearitmética binaria, unión de arrays y operadores de strings que permiten usar un valor en una expresión y entonces establecer su valor como el resultado de esa expresión. Por ejemplo:
<?php
$a=3;
$a+=5;// establece $a en 8, como si se hubiera dicho: $a = $a + 5;
$b="Hola ";
$b.="ahí!";// establece $b en "Hola ahí!", al igual que $b = $b . "ahí!";
?>Observe que la asignación copia la variable original en la nueva (asignación por valor), por lo que los cambios en una no afectarán a la otra. Esto también puede tener relevancia si se necesita copiar algo como un gran array dentro de un bucle estrecho.
Una excepción al comportamiento usual de la asignación por valor en PHP ocurre conobjects los cuales son asignados por referencia en PHP 5. Los objetos pueden ser explícitamente copiados por medio de la palabra claveclone.
La asignación por referencia también está soportada, utilizando la sintaxis "$var = &$othervar;". Asignación por referencia significa que ambas variables terminan apuntando a los mismos datos y nada es copiado en ninguna parte.
Ejemplo #1 Asignación por referencia
<?php
$a=3;
$b= &$a;// $b es una referencia para $a
print"$a\n";// muestra 3
print"$b\n";// muestra 3
$a=4;// cambia $a
print"$a\n";// muestra 4
print"$b\n";// muestra 4 también, dado que $b es una referencia para $a, la cual ha
// sido cambiada
?>Desde PHP 5, el operadornewretorna una referencia automáticamente, así que asignar el resultado denewpor referencia, resulta en un mensajeE_DEPRECATEDen PHP 5.3 y posteriores y un mensajeE_STRICTen versiones anteriores.
Por ejemplo, éste código resultará en una advertencia:
<?php
classC{}
/* La siguiente línea genera el siguiente mensaje de error:
* Deprecated: Assigning the return value of new by reference is deprecated in...
*/
$o= &newC;
?>Más información sobre referencias y sus usos potenciales se puede encontrar en la sección del manualReferencias Explicadas
Los operadores bit a bit permiten la evaluación y la manipulación de bits específicos dentro de un integer.
| Ejemplo | Nombre | Resultado |
|---|---|---|
$a & $b | And (y) | Los bits que están activos en ambos$ay$bson activados. |
$a | $b | Or (o inclusivo) | Los bits que están activos ya sea en$ao en$bson activados. |
$a ^ $b | Xor (o exclusivo) | Los bits que están activos en$ao en$b, pero no en ambos, son activados. |
~ $a | Not (no) | Los bits que están activos en$ason desactivados, y viceversa. |
$a << $b | Shift left(desplazamiento a izquierda) | Desplaza los bits de$a,$bpasos a la izquierda (cada paso quiere decir "multiplicar por dos"). |
$a >> $b | Shift right (desplazamiento a derecha) | Desplaza los bits de$a,$bpasos a la derecha (cada paso quiere decir "dividir por dos"). |
El desplazamiento de bits en PHP es aritmético. Los bits desplazados por fuera de cualquiera de los extremos son descartados. Desplazamientos de izquierda tienen ceros desplazados a la derecha mientras que el bit de signo es desplazado fuera a la izquierda, es decir que no se conserva el signo de un operando. Desplazamientos a la derecha tienen copias del bit de signo desplazado a la izquierda, es decir que se conserva el signo de un operando.
Utilice paréntesis para garantizar laprecedenciadeseada. Por ejemplo,$a & $b == trueevalúa la equivalencia y luego el bit a bit, mientras que($a & $b) == trueevalúa el bit a bit y luego la equivalencia.
Si los operandos para los operadores&,|y^son string, la operación se realizará con los valores ASCII de los caracteres que componen dichos string, y el resultado será también un string. En todos los demás casos, ambos operandos seránconvertidos a valores de tipo integery el resultado será también un integer.
Si el operando del operados~es un string, la operación se realizará con valores los ASCII de los caracteres que componen dicho string, y el resultado también será un string; en caso contrario, el operando y el resultado serán tratados como valores de tipo integer.
Ambos operandos y el resultado de lo operadores<<y>>siempre son tratados como valores de tipo integer.
El ajuste ini error_reporting utiliza valores a nivel de bit,
lo que ofrece una demostración del mundo real de desactivar
bits. Para mostrar todos los errores, a excepción de los avisos,
las instrucciones del archivo php.ini dicen utilizar:
E_ALL & ~E_NOTICE
Esto funciona iniciando con E_ALL:
00000000000000000111011111111111
Luego se toma el valor de E_NOTICE ...
00000000000000000000000000001000
... y se invierte por medio de ~:
11111111111111111111111111110111
Finalmente, se utiliza AND (&) para encontrar los bits que se
activaron en ambos valores:
00000000000000000111011111110111
Otra forma de lograrlo es mediante XOR (^)
para encontrar los bits que están activados en sólo el primer valor o en el otro:
E_ALL ^ E_NOTICE
error_reporting también se puede utilizar para demostrar la activación de bits.
La forma para mostrar sólo los errores y los errores recuperables es:
E_ERROR | E_RECOVERABLE_ERROR
Este proceso combina E_ERROR
00000000000000000000000000000001
y
00000000000000000001000000000000
usando el operador OR (|)
para obtener los bits activados en cualquiera de estos valores:
00000000000000000001000000000001
Ejemplo #1 Operaciones AND, OR y XOR bit a bit sobre integers
<?php
/*
* Ignore la sección superior,
* es sólo el formateado para hacer la salida más clara.
*/
$format='(%1$2d = %1$04b) = (%2$2d = %2$04b)'
.' %3$s (%4$2d = %4$04b)'."\n";
echo <<<EOH
--------- --------- -- ---------
resultado valor op prueba
--------- --------- -- ---------
EOH;
/*
* Aquí están los ejemplos.
*/
$values= array(0,1,2,4,8);
$test=1+4;
echo"\n AND bit a bit \n";
foreach ($valuesas$value) {
$result=$value&$test;
printf($format,$result,$value,'&',$test);
}
echo"\n OR inclusivo bit a bit \n";
foreach ($valuesas$value) {
$result=$value|$test;
printf($format,$result,$value,'|',$test);
}
echo"\n OR exclusivo (XOR) bit a bit \n";
foreach ($valuesas$value) {
$result=$value^$test;
printf($format,$result,$value,'^',$test);
}
?>El resultado del ejemplo sería:
--------- --------- -- --------- resultado valor op prueba --------- --------- -- --------- AND bit a bit ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101) ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101) ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101) ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101) ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101) OR inclusivo bit a bit ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101) ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101) ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101) ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101) (13 = 1101) = ( 8 = 1000) | ( 5 = 0101) OR exclusivo (XOR) bit a bit ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101) ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101) ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101) ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101) (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)
Ejemplo #2 Operaciones XOR bit a bit sobre strings
<?php
echo12^9;// Sale '5'
echo"12"^"9";// Sale el caracter de retroceso (ascii 8)
// ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8
echo"hallo"^"hello";// Salen los valores ascii #0 #4 #0 #0 #0
// 'a' ^ 'e' = #4
echo2^"3";// Sale 1
// 2 ^ ((int)"3") == 1
echo"2"^3;// Sale 1
// ((int)"2") ^ 3 == 1
?>Ejemplo #3 Desplazamiento de bits sobre integers
<?php
/*
* Aquí están los ejemplos.
*/
echo"\n--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS ---\n";
$val=4;
$places=1;
$res=$val>>$places;
p($res,$val,'>>',$places,'copia del bit de signo desplazado hacia el lado izquierdo');
$val=4;
$places=2;
$res=$val>>$places;
p($res,$val,'>>',$places);
$val=4;
$places=3;
$res=$val>>$places;
p($res,$val,'>>',$places,'bits desplazados fuera del lado derecho');
$val=4;
$places=4;
$res=$val>>$places;
p($res,$val,'>>',$places,'mismo resultado que arriba; no se puede desplazar más allá del 0');
echo"\n--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS ---\n";
$val= -4;
$places=1;
$res=$val>>$places;
p($res,$val,'>>',$places,'copia del bit de signo desplazado al lado izquierdo');
$val= -4;
$places=2;
$res=$val>>$places;
p($res,$val,'>>',$places,'bits desplazados fuera del lado derecho');
$val= -4;
$places=3;
$res=$val>>$places;
p($res,$val,'>>',$places,'mismo resultado que arriba; no se puede desplazar más allá del -1');
echo"\n--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS ---\n";
$val=4;
$places=1;
$res=$val<<$places;
p($res,$val,'<<',$places,'ceros rellenan en el lado derecho');
$val=4;
$places= (PHP_INT_SIZE*8) -4;
$res=$val<<$places;
p($res,$val,'<<',$places);
$val=4;
$places= (PHP_INT_SIZE*8) -3;
$res=$val<<$places;
p($res,$val,'<<',$places,'bit de signo resulta desplazado fuera');
$val=4;
$places= (PHP_INT_SIZE*8) -2;
$res=$val<<$places;
p($res,$val,'<<',$places,'bit de signo desplazado fuera del lado izquierdo');
echo"\n--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS ---\n";
$val= -4;
$places=1;
$res=$val<<$places;
p($res,$val,'<<',$places,'ceros rellenan en el lado derecho');
$val= -4;
$places= (PHP_INT_SIZE*8) -3;
$res=$val<<$places;
p($res,$val,'<<',$places);
$val= -4;
$places= (PHP_INT_SIZE*8) -2;
$res=$val<<$places;
p($res,$val,'<<',$places,'bits desplazados fuera del lado izquierdo, incluyendo el bit de signo');
/*
* Ignore this bottom section,
* it is just formatting to make output clearer.
*/
functionp($res,$val,$op,$places,$note='') {
$format='%0'. (PHP_INT_SIZE*8) ."b\n";
printf("Expression: %d = %d %s %d\n",$res,$val,$op,$places);
echo" Decimal:\n";
printf(" val=%d\n",$val);
printf(" res=%d\n",$res);
echo" Binary:\n";
printf(' val='.$format,$val);
printf(' res='.$format,$res);
if ($note) {
echo" NOTE:$note\n";
}
echo"\n";
}
?>El resultado del ejemplo en equipos de 32 bit sería:
--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS --- Expression: 2 = 4 >> 1 Decimal: val=4 res=2 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000010 NOTE: copia del bit de signo desplazado hacia el lado izquierdo Expression: 1 = 4 >> 2 Decimal: val=4 res=1 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000001 Expression: 0 = 4 >> 3 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: bits desplazados fuera del lado derecho Expression: 0 = 4 >> 4 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: mismo resultado que arriba; no se puede desplazar más allá del 0 --- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS --- Expression: -2 = -4 >> 1 Decimal: val=-4 res=-2 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111110 NOTE: copia del bit de signo desplazado al lado izquierdo Expression: -1 = -4 >> 2 Decimal: val=-4 res=-1 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111111 NOTE: bits desplazados fuera del lado derecho Expression: -1 = -4 >> 3 Decimal: val=-4 res=-1 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111111 NOTE: mismo resultado que arriba; no se puede desplazar más allá del -1 --- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS --- Expression: 8 = 4 << 1 Decimal: val=4 res=8 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000001000 NOTE: ceros rellenan en el lado derecho Expression: 1073741824 = 4 << 28 Decimal: val=4 res=1073741824 Binary: val=00000000000000000000000000000100 res=01000000000000000000000000000000 Expression: -2147483648 = 4 << 29 Decimal: val=4 res=-2147483648 Binary: val=00000000000000000000000000000100 res=10000000000000000000000000000000 NOTE: bit de signo resulta desplazado fuera Expression: 0 = 4 << 30 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: bit de signo desplazado fuera del lado izquierdo --- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS --- Expression: -8 = -4 << 1 Decimal: val=-4 res=-8 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111000 NOTE: ceros rellenan en el lado derecho Expression: -2147483648 = -4 << 29 Decimal: val=-4 res=-2147483648 Binary: val=11111111111111111111111111111100 res=10000000000000000000000000000000 Expression: 0 = -4 << 30 Decimal: val=-4 res=0 Binary: val=11111111111111111111111111111100 res=00000000000000000000000000000000 NOTE: bits desplazados fuera del lado izquierdo, incluyendo el bit de signo
El resultado del ejemplo en equipos de 64 bit sería:
--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS --- Expression: 2 = 4 >> 1 Decimal: val=4 res=2 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000010 NOTE: copia del bit de signo desplazado hacia el lado izquierdo Expression: 1 = 4 >> 2 Decimal: val=4 res=1 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000001 Expression: 0 = 4 >> 3 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bits desplazados fuera del lado derecho Expression: 0 = 4 >> 4 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: mismo resultado que arriba; no se puede desplazar más allá del 0 --- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS --- Expression: -2 = -4 >> 1 Decimal: val=-4 res=-2 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111110 NOTE: copia del bit de signo desplazado al lado izquierdo Expression: -1 = -4 >> 2 Decimal: val=-4 res=-1 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111111 NOTE: bits desplazados fuera del lado derecho Expression: -1 = -4 >> 3 Decimal: val=-4 res=-1 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111111 NOTE: mismo resultado que arriba; no se puede desplazar más allá del -1 --- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS --- Expression: 8 = 4 << 1 Decimal: val=4 res=8 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000001000 NOTE: ceros rellenan en el lado derecho Expression: 4611686018427387904 = 4 << 60 Decimal: val=4 res=4611686018427387904 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0100000000000000000000000000000000000000000000000000000000000000 Expression: -9223372036854775808 = 4 << 61 Decimal: val=4 res=-9223372036854775808 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=1000000000000000000000000000000000000000000000000000000000000000 NOTE: bit de signo resulta desplazado fuera Expression: 0 = 4 << 62 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bit de signo desplazado fuera del lado izquierdo --- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS --- Expression: -8 = -4 << 1 Decimal: val=-4 res=-8 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111000 NOTE: ceros rellenan en el lado derecho Expression: -9223372036854775808 = -4 << 61 Decimal: val=-4 res=-9223372036854775808 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1000000000000000000000000000000000000000000000000000000000000000 Expression: 0 = -4 << 62 Decimal: val=-4 res=0 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bits desplazados fuera del lado izquierdo, incluyendo el bit de signo
Desplazar un integer por valores mayores o iguales al ancho del tipo long integer del sistema resultará en un comportamiento indefinido. En otras palabras, no desplace más de 31 bit en sistemas de 32 bit, y no desplace más de 63 bit en sistemas de 64 bit.
Use funciones de la extensióngmppara manipular a nivel de bit números mayores quePHP_INT_MAX.
Ver tambiénpack(),unpack(),gmp_and(),gmp_or(),gmp_xor(),gmp_testbit(),gmp_clrbit()
Los operadores de comparación, como su nombre lo indica, permiten comparar dos valores. Puede también estar interesado en verlas tablas de comparación de tipos, ya que muestran ejemplos de las varias comparaciones relacionadas con tipos.
| Ejemplo | Nombre | Resultado |
|---|---|---|
| $a == $b | Igual | truesi$aes igual a$bdespués de la manipulación de tipos. |
| $a === $b | Idéntico | truesi$aes igual a$b, y son del mismo tipo. |
| $a != $b | Diferente | truesi$ano es igual a$bdespués de la manipulación de tipos. |
| $a <> $b | Diferente | truesi$ano es igual a$bdespués de la manipulación de tipos. |
| $a !== $b | No idéntico | truesi$ano es igual a$b, o si no son del mismo tipo. |
| $a < $b | Menor que | truesi$aes estrictamente menor que$b. |
| $a > $b | Mayor que | truesi$aes estrictamente mayor que$b. |
| $a <= $b | Menor o igual que | truesi$aes menor o igual que$b. |
| $a >= $b | Mayor o igual que | truesi$aes mayor o igual que$b. |
| $a <=> $b | Nave espacial | Unintegermenor que, igual a, o mayor que cero cuando$aes respectivamente menor que, igual a, o mayor que$b. Disponible a partir de PHP 7. |
| $a ?? $b ?? $c | Fusión de null | El primer operando de izquierda a derecha que exista y no seanull.nullsi no hay valores definidos y no sonnull. Disponible a partir de PHP 7. |
Si se compara un número con un string o la comparación implica strings numéricos, entonces cada string esconvertido en un númeroy la comparación realizada numéricamente. Estas reglas también se aplican a la sentenciaswitch. La conversión de tipo no tiene lugar cuando la comparación es === o !== ya que esto involucra comparar el tipo así como el valor.
<?php
var_dump(0=="a");// 0 == 0 -> true
var_dump("1"=="01");// 1 == 1 -> true
var_dump("10"=="1e1");// 10 == 10 -> true
var_dump(100=="1e2");// 100 == 100 -> true
switch ("a") {
case0:
echo"0";
break;
case"a":// nunca alcanzado debido a que "a" ya ha coincidido con 0
echo"a";
break;
}
?><?php
// Integers
echo1<=>1;// 0
echo1<=>2;// -1
echo2<=>1;// 1
// Floats
echo1.5<=>1.5;// 0
echo1.5<=>2.5;// -1
echo2.5<=>1.5;// 1
// Strings
echo"a"<=>"a";// 0
echo"a"<=>"b";// -1
echo"b"<=>"a";// 1
echo"a"<=>"aa";// -1
echo"zz"<=>"aa";// 1
// Arrays
echo [] <=> [];// 0
echo [1,2,3] <=> [1,2,3];// 0
echo [1,2,3] <=> [];// 1
echo [1,2,3] <=> [1,2,1];// 1
echo [1,2,3] <=> [1,2,4];// -1
// Objects
$a= (object) ["a"=>"b"];
$b= (object) ["a"=>"b"];
echo$a<=>$b;// 0
$a= (object) ["a"=>"b"];
$b= (object) ["a"=>"c"];
echo$a<=>$b;// -1
$a= (object) ["a"=>"c"];
$b= (object) ["a"=>"b"];
echo$a<=>$b;// 1
// only values are compared
$a= (object) ["a"=>"b"];
$b= (object) ["b"=>"b"];
echo$a<=>$b;// 1
?>Para varios tipos, la comparación se realiza de acuerdo a la siguiente tabla (en orden).
| Tipo de operando 1 | Tipo de operando 2 | Resultado |
|---|---|---|
| nullostring | string | Conviertenullen "", comparación numérica o léxica |
| boolonull | cualquiera | Convierte ambos lados abool,false<true |
| object | object | Las clases internas pueden definir su propia comparación, diferentes clases son incomparables, la misma clase - comparan propiedades en la misma forma que los arrays (PHP 4), PHP 5 tiene su propiaexplicación |
| string,resourceonumber | string,resourceonumber | Traducir las cadenas y recursos a números, matemática usual |
| array | array | Un array con menos elementos es menor, si una clave del operando 1 no se encuentra en el operando 2 entonces los arrays son incomparables, de otra forma - compara valor por valor (ver el siguiente ejemplo) |
| object | cualquiera | objectes siempre mayor |
| array | cualquiera | arrayes siempre mayor |
Ejemplo #1 Comparación boolean/null
<?php
// Booleanos y null son comparados siempre coomo bool
var_dump(1==TRUE);// TRUE - same as (bool)1 == TRUE
var_dump(0==FALSE);// TRUE - same as (bool)0 == FALSE
var_dump(100<TRUE);// FALSE - same as (bool)100 < TRUE
var_dump(-10<FALSE);// FALSE - same as (bool)-10 < FALSE
var_dump(min(-100, -10,NULL,10,100));// NULL - (bool)NULL < (bool)-100 is FALSE < TRUE
?>Ejemplo #2 Transcripción de la comparación estándar de arrays
<?php
// Arrays son comparados de esta forma con los operadores de comparación estándar
functionstandard_array_compare($op1,$op2)
{
if (count($op1) <count($op2)) {
return -1;// $op1 < $op2
} elseif (count($op1) >count($op2)) {
return1;// $op1 > $op2
}
foreach ($op1as$key=>$val) {
if (!array_key_exists($key,$op2)) {
returnnull;// uncomparable
} elseif ($val<$op2[$key]) {
return -1;
} elseif ($val>$op2[$key]) {
return1;
}
}
return0;// $op1 == $op2
}
?>Ver tambiénstrcasecmp(),strcmp(),operadores de array, y la sección del manual sobretipos.
Debido a la forma en que son representados internamente losfloats, no se deben probar por igualdad dosfloats.
Ver la documentación defloatpara más información.
Otro operador condicional es el operador "?:" (o ternario).
Ejemplo #3 Asignación de un valor predeterminado
<?php
// Ejemplo de uso para: Operador Ternario
$action= (empty($_POST['action'])) ?'default':$_POST['action'];
// Lo anterior es idéntico a esta sentencia if/else
if (empty($_POST['action'])) {
$action='default';
} else {
$action=$_POST['action'];
}
?>(expr1) ? (expr2) : (expr3)evalúa aexpr2siexpr1se evalúa comotruey aexpr3siexpr1se evalúa comofalse.A partir de PHP 5.3, es posible dejar de lado la parte media del operador ternario. La expresiónexpr1 ?: expr3retornaexpr1siexpr1se evalúa comotrueyexpr3si es de otra manera.
Nota:Por favor note que el operador ternario es una expresión, y que no evalúa a una variable, sino al resultado de una expresión. Esto es importante saberlo si se desea retornar una variable por referencia. La sentencia
return $var == 42 ? $a : $b;en una función con retorno-por-referencia no funcionará por lo que se ha mencionado y una advertencia es generada en versiones posteriores de PHP.
Nota:
Es recomendable evitar el "apilamiento" expresiones ternarias. El comportamiento de PHP al utilizar más de un operador ternario en una única sentencia no es evidente:
Ejemplo #4 Comportamiento Ternario poco obvio
<?php
// a primera vista, lo siguiente parece tener la salida de 'true'
echo (true?'true':false?'t':'f');
// sin embargo, la salida real de lo anterior es 't'
// esto se debe a que las expresiones ternarias se evalúan de izquierda a derecha
// la siguiente es una versión más obvia del mismo código anterior
echo ((true?'true':false) ?'t':'f');
// aquí, se puede ver que la primera expresión es evaluada como 'true', que
// a su vez se evalúa como (bool)true, retornando así la rama verdadera de la
// segunda expresión ternaria.
?>
Further exists the "??" (or null coalescing) operator.
Ejemplo #5 Assigning a default value
<?php
// Example usage for: Null Coalesce Operator
$action=$_POST['action'] ??'default';
// The above is identical to this if/else statement
if (isset($_POST['action'])) {
$action=$_POST['action'];
} else {
$action='default';
}
?>(expr1) ?? (expr2)evaluates toexpr2ifexpr1isnull, andexpr1otherwise.In particular, this operator does not emit a notice or warning if the left-hand side value does not exist, just likeisset(). This is especially useful on array keys.
Nota:Please note that the null coalescing operator is an expression, and that it doesn't evaluate to a variable, but to the result of an expression. This is important to know if you want to return a variable by reference. The statement
return $foo ?? $bar;in a return-by-reference function will therefore not work and a warning is issued.
Nota:
Please note that the null coalescing operator allows for simple nesting:
Ejemplo #6 Nesting null coalescing operator
<?php
$foo=null;
$bar=null;
$baz=1;
$qux=2;
echo$foo??$bar??$baz??$qux;// outputs 1
?>
PHP soporta un operador de control de errores: el signo de arroba (@). Cuando se antepone a una expresión en PHP, cualquier mensaje de error que pueden ser generado por esa expresión será ignorado.
Si se ha establecido una función controladora de errores personalizada conset_error_handler()entonces todavía será llamada, pero este controlador de errores personalizado puede (y debe) llamar aerror_reporting()el cual devolverá 0 cuando la llamada que provocó el error fue precedida por el signo @.
Si la propiedadtrack_errorsestá activada, cualquier mensaje de error generado por la expresión será guardada en la variable$php_errormsg. Esta variable se sobrescribe en cada error, así que se debe comprobar antes si se desea utilizar.
<?php
/* Error intencional de archivo */
$my_file= @file('non_existent_file') or
die ("La apertura de archivo ha fallado: el error fue '$php_errormsg'");
// esto funciona con cualquier expresión, no solo con funciones:
$value= @$cache[$key];
// no producirá una anotación si el índice $key no existe.
?>Nota:El operador @ trabaja sólo sobreexpresiones. Una simple regla de oro es: si se puede tomar el valor de algo, entonces se le puede anteponer el operador @. Por ejemplo, puede anteponerse a variables, a llamadas a funciones eincludes, constantes y así sucesivamente. No puede anteponerse a definiciones de función o clase, ni a estructuras condicionales como
ifyforeach, y así sucesivamente.
Ver tambiénerror_reporting()y la sección del manual sobrefunciones de Manejo de Errores y Registros.
En la actualidad, el operador de prefijo "@" para control de errores deshabilitará incluso el reporte de errores en casos de fallos críticos que terminarán la ejecución del script. Entre otras cosas, esto quiere decir que si se usa "@" para eliminar los errores de una cierta función y ésta no se encuentra disponible o ha sido escrita de forma incorrecta, el script se detendrá en ese punto sin indicación de por qué.
PHP soporta un operador de ejecución: las comillas invertidas (``). ¡Note que estas no son las comillas sencillas! PHP intentará ejecutar el contenido entre las comillas invertidas como si se tratara de un comando del shell; la salida será retornada (es decir, no será simplemente volcada como salida; puede ser asignada a una variable). El uso del operador de comillas invertidas es idéntico al deshell_exec().
<?php
$output= `ls -al`;
echo"<pre>$output</pre>";
?>Nota:
El operador de comillas invertidas se deshabilita cuandoshell_exec()esta desactivado.
Nota:
A diferencia de otros lenguajes, las comillas invertidas no tienen un significa especial dentro de string entre comillas dobles.
Vea también la sección del manual sobrefunciones de ejecución de programas,popen()proc_open()yUsando PHP desde la línea de comandos.
PHP soporta operadores estilo C de pre- y post-incremento y decremento.
Nota:Los operadores de incremento/decremento solamente afectan a números y strings. Los arrays, objects y resources no se ven afectados. Decrementar valores
nulltampoco tiene efecto, pero incrementarlos entonces resulta en1.
| Ejemplo | Nombre | Efecto |
|---|---|---|
| ++$a | Pre-incremento | Incrementa$aen uno, y luego retorna$a. |
| $a++ | Post-incremento | Retorna$a, y luego incrementa$aen uno. |
| --$a | Pre-decremento | Decrementa$aen uno, luego retorna$a. |
| $a-- | Post-decremento | Retorna$a, luego decrementa$aen uno. |
Aquí hay un script simple de ejemplo:
<?php
echo"<h3>Postincremento</h3>";
$a=5;
echo"Debe ser 5: ".$a++ ."<br />\n";
echo"Debe ser 6: ".$a."<br />\n";
echo"<h3>Preincremento</h3>";
$a=5;
echo"Debe ser 6: ". ++$a."<br />\n";
echo"Debe ser 6: ".$a."<br />\n";
echo"<h3>Postdecremento</h3>";
$a=5;
echo"Debe ser 5: ".$a-- ."<br />\n";
echo"Debe ser 4: ".$a."<br />\n";
echo"<h3>Predecremento</h3>";
$a=5;
echo"Debe ser 4: ". --$a."<br />\n";
echo"Debe ser 4: ".$a."<br />\n";
?>PHP sigue la convención de Perl cuando trabaja con operaciones aritméticas sobre variables de caracteres y no la de C. Por ejemplo, en PHP y Perl$a = 'Z'; $a++;convierte$aen'AA', mientras que en Ca = 'Z'; a++;convierteaen'['(el valor ASCII de'Z'es 90, el valor ASCII de'['es 91). Nótese que las variables de caracteres pueden ser incrementadas pero no decrementadas y aun así sólo caracteres y dígitos de ASCII puro (a-z, A-Z y 0-9) están soportados. Incrementar o decrementar otras variables de caracteres no tiene efecto, el string original no se modifica.
Ejemplo #1 Operaciones aritméticas sobre variables de caracteres
<?php
echo'== Letras =='.PHP_EOL;
$s='W';
for ($n=0;$n<6;$n++) {
echo ++$s.PHP_EOL;
}
// Los caracteres de dígitos tienen un comportamiento diferente
echo'== Dígitos =='.PHP_EOL;
$d='A8';
for ($n=0;$n<6;$n++) {
echo ++$d.PHP_EOL;
}
$d='A08';
for ($n=0;$n<6;$n++) {
echo ++$d.PHP_EOL;
}
?>El resultado del ejemplo sería:
== Letras == X Y Z AA AB AC == Dígitos == A9 B0 B1 B2 B3 B4 A09 A10 A11 A12 A13 A14
Incrementar o decrementar booleanos no tiene efecto.
| Ejemplo | Nombre | Resultado |
|---|---|---|
| $a and $b | And (y) | truesi tanto$acomo$bsontrue. |
| $a or $b | Or (o inclusivo) | truesi cualquiera de$ao$bestrue. |
| $a xor $b | Xor (o exclusivo) | truesi$ao$bestrue, pero no ambos. |
| ! $a | Not (no) | truesi$ano estrue. |
| $a && $b | And (y) | truesi tanto$acomo$bsontrue. |
| $a || $b | Or (o inclusivo) | truesi cualquiera de$ao$bestrue. |
La razón para tener las dos variaciones diferentes de los operadores "and" y "or" es que ellos operan con precedencias diferentes. (VerPrecedencia de operadores.)
Ejemplo #1 Los operadores lógicos ilustrados
<?php
// --------------------
// foo() nunca será llamado ya que los operadores están en cortocircuito
$a= (false&&foo());
$b= (true||foo());
$c= (falseandfoo());
$d= (trueorfoo());
// --------------------
// "||" tiene una precedencia mayor que "or"
// El resultado de la expresión (false || true) es asignado a $e
// Actúa como: ($e = (false || true))
$e=false||true;
// La constante false es asignada a $f antes de que suceda la operación "or"
// Actúa como: (($f = false) or true)
$f=falseortrue;
var_dump($e,$f);
// --------------------
// "&&" tiene una precedencia mayor que "and"
// El resultado de la expresión (true && false) es asignado a $g
// Actúa como: ($g = (true && false))
$g=true&&false;
// La constante true es asignada a $h antes de que suceda la operación "and"
// Actúa como: (($h = true) and false)
$h=trueandfalse;
var_dump($g,$h);
?>El resultado del ejemplo sería algo similar a:
bool(true) bool(false) bool(false) bool(true)
Existen dos operadores para datos tipostring. El primero es el operador de concatenación ('.'), el cual retorna el resultado de concatenar sus argumentos derecho e izquierdo. El segundo es el operador de asignación sobre concatenación ('.='), el cual añade el argumento del lado derecho al argumento en el lado izquierdo. Por favor consulteOperadores de asignaciónpara más información.
<?php
$a="Hello ";
$b=$a."World!";// ahora $b contiene "Hello World!"
$a="Hello ";
$a.="World!";// ahora $a contiene "Hello World!"
?>Ver también las secciones del manual sobre eltipo stringy lasfunciones de strings.
| Ejemplo | Nombre | Resultado |
|---|---|---|
| $a + $b | Unión | Unión de$ay$b. |
| $a == $b | Igualdad | truesi$ai$btienen las mismas parejas clave/valor. |
| $a === $b | Identidad | truesi$ay$btienen las mismas parejas clave/valor en el mismo orden y de los mismos tipos. |
| $a != $b | Desigualdad | truesi$ano es igual a$b. |
| $a <> $b | Desigualdad | truesi$ano es igual a$b. |
| $a !== $b | No-identidad | truesi$ano es idéntica a$b. |
El operador+devuelve el array del lado derecho añadido al array del lado izquierdo; para las claves que existan en ambos arrays, serán utilizados los elementos del array de la izquierda y serán ignorados los elementos correspondientes del array de la derecha.
<?php
$a= array("a"=>"apple","b"=>"banana");
$b= array("a"=>"pear","b"=>"strawberry","c"=>"cherry");
$c=$a+$b;// Unión de $a y $b
echo"Unión de \$a y \$b: \n";
var_dump($c);
$c=$b+$a;// Unión de $b y $a
echo"Unión de \$b y \$a: \n";
var_dump($c);
$a+=$b;// Unión de $a += $b es $a y $b
echo"Unión de \$a += \$b: \n";
var_dump($a);
?>
Unión de $a y $b:
array(3) {
["a"]=>
string(5) "apple"
["b"]=>
string(6) "banana"
["c"]=>
string(6) "cherry"
}
Unión de $b y $a:
array(3) {
["a"]=>
string(4) "pear"
["b"]=>
string(10) "strawberry"
["c"]=>
string(6) "cherry"
}
Unión de $a += $b:
array(3) {
'a' =>
string(5) "apple"
'b' =>
string(6) "banana"
'c' =>
string(6) "cherry"
}
Los elementos de los arrays son iguales para la comparación si éstos tienen la misma clave y valor.
Ejemplo #1 Comparando arrays
<?php
$a= array("apple","banana");
$b= array(1=>"banana","0"=>"apple");
var_dump($a==$b);// bool(true)
var_dump($a===$b);// bool(false)
?>Ver también las secciones del manual sobre eltipo arrayyfunciones de arrays.
instanceofse utiliza para determinar si una variable de PHP es un objeto instanciado de una ciertaclase:
Ejemplo #1 Utilizandoinstanceofcon clases
<?php
classMyClass
{
}
classNotMyClass
{
}
$a= newMyClass;
var_dump($ainstanceofMyClass);
var_dump($ainstanceofNotMyClass);
?>El resultado del ejemplo sería:
bool(true) bool(false)
instanceoftambién se puede utilizar para determinar si una variable es un objeto instanciado de una clase que hereda de una clase padre:
Ejemplo #2 Utilizandoinstanceofcon clases heredadas
<?php
classParentClass
{
}
classMyClassextendsParentClass
{
}
$a= newMyClass;
var_dump($ainstanceofMyClass);
var_dump($ainstanceofParentClass);
?>El resultado del ejemplo sería:
bool(true) bool(true)
Para comprobar si un objetonoes una instancia de una clase, se puede usar eloperador lógiconot.
Ejemplo #3 Utilizandoinstanceofpara verificar si un objetonoes una instancia de una clase
<?php
classMyClass
{
}
$a= newMyClass;
var_dump(!($ainstanceofstdClass));
?>El resultado del ejemplo sería:
bool(true)
Finalmente,instanceoftambién se puede utilizar para determinar si una variable es un objeto instanciado de una clase que implementa unainterface:
Ejemplo #4 Utilizandoinstanceofpara la clase
<?php
interfaceMyInterface
{
}
classMyClassimplementsMyInterface
{
}
$a= newMyClass;
var_dump($ainstanceofMyClass);
var_dump($ainstanceofMyInterface);
?>El resultado del ejemplo sería:
bool(true) bool(true)
Aunqueinstanceofse utiliza generalmente con un nombre de clase literal, también puede ser utilizado con otro objeto o una variable string:
Ejemplo #5 Utilizandoinstanceofcon otras variables
<?php
interfaceMyInterface
{
}
classMyClassimplementsMyInterface
{
}
$a= newMyClass;
$b= newMyClass;
$c='MyClass';
$d='NotMyClass';
var_dump($ainstanceof$b);// $b is an object of class MyClass
var_dump($ainstanceof$c);// $c is a string 'MyClass'
var_dump($ainstanceof$d);// $d is a string 'NotMyClass'
?>El resultado del ejemplo sería:
bool(true) bool(true) bool(false)
instanceof no lanza ningún error si la variable que está siendo comprobada no es un objeto, simplemente devuelvefalse. Las constantes, sin embargo, no está permitidas.
Ejemplo #6 Usarinstanceofpara comprobar otras variables
<?php
$a=1;
$b=NULL;
$c=imagecreate(5,5);
var_dump($ainstanceofstdClass);// $a es un entero
var_dump($binstanceofstdClass);// $b es NULL
var_dump($cinstanceofstdClass);// $c es un recurso
var_dump(FALSEinstanceofstdClass);
?>El resultado del ejemplo sería:
bool(false) bool(false) bool(false) PHP Fatal error: instanceof expects an object instance, constant given
Hay algunas trampas a tener en cuenta. Antes de versión de PHP 5.1.0,instanceofllamaría a__autoload()si el nombre de clase no existía. Además, si la clase no estaba cargada, un error fatal ocurriría. Esto se puede solucionar mediante una referencia de clase dinámica o una variable string que contenga el nombre de la clase:
Ejemplo #7 Evitando búsquedas del nombre de clase y errores fatales coninstanceofen PHP 5.0
<?php
$d='NotMyClass';
var_dump($ainstanceof$d);// aquí no hay error fatal
?>El resultado del ejemplo sería:
bool(false)
El operadorinstanceoffue introducido en PHP 5. Antes de esta época se utilizabais_a(), pero desde entoncesis_a()se ha quedado obsoleto en favor deinstanceof. Tenga en cuenta que a partir de PHP 5.3.0,is_a()ya no está obsoleto.
Ver tambiénget_class()yis_a().
Todo script PHP está construido según una serie de sentencias. Una sentencia puede ser una asignación, una llamada de función, un ciclo, una sentencia condicional o incluso una sentencia que no hace nada (una sentencia vacía). Las sentencias generalmente finalizan con un punto y coma. Adicionalmente, las sentencias pueden agruparse en un conjunto de sentencias, encapsulándolas entre corchetes. Un grupo de sentencias es una sentencia por sí misma también. Los diferentes tipos de sentencias son descritos en este capítulo.
if(PHP 4, PHP 5, PHP 7, PHP 8)
El constructorifes una de las características más importantes de muchos lenguajes, incluido PHP. Permite la ejecución condicional de fragmentos de código. PHP dispone de una estructuraifque es similar a la de C:
if (expr) sentencia
Como se describe enla sección sobre expresiones, laexpresiónes evaluada a su valor booleano. Si laexpresiónse evalúa comotrue, PHP ejecutará lasentenciay si se evalúa comofalsela ignorará. Más información sobre qué valores evalúan comofalsese puede encontrar en la sección'Convirtiendo a booleano'.
El siguiente ejemplo mostraríaa es mayor que bsi$aes mayor que$b:
<?php
if ($a>$b) {
echo"a es mayor que b";
}
?>A menudo se desea tener más de una sentencia para ser ejecutada condicionalmente. Por supuesto, no hay necesidad de envolver cada sentencia con una cláusulaif. En cambio, se pueden agrupar varias sentencias en un grupo de sentencias. Por ejemplo, este código mostraríaa es mayor que bsi$aes mayor que$by entonces asignaría el valor de$aa$b:
<?php
if ($a>$b) {
echo"a es mayor que b";
$b=$a;
}
?>Las sentenciasifpueden anidarse dentro de otra sentenciasifinfinitamente, lo cual provee completa flexibilidad para la ejecución condicional de diferentes partes del programa.
else(PHP 4, PHP 5, PHP 7, PHP 8)
Con frecuencia se desea ejecutar una sentencia si una determinada condición se cumple y una sentencia diferente si la condición no se cumple. Esto es para lo que sirveelse. Elelseextiende una sentenciaifpara ejecutar una sentencia en caso que la expresión en la sentenciaifse evalúe comofalse. Por ejemplo, el siguiente código deberá mostrara es mayor que bsi$aes mayor que$bya NO es mayor que ben el caso contrario:
<?php
if ($a>$b) {
echo"a es mayor que b";
} else {
echo"a NO es mayor que b";
}
?>elsesólo es ejecutada si la expresiónifes evaluada comofalsey si hay algunas expresioneselseif- sólo se ejecuta si también todas son evaluadas comofalse(verelseif).elseif/else if(PHP 4, PHP 5, PHP 7, PHP 8)
elseif, como su nombre lo sugiere, es una combinación deifyelse. Del mismo modo queelse, extiende una sentenciaifpara ejecutar una sentencia diferente en caso que la expresióniforiginal se evalúe comofalse. Sin embargo, a diferencia deelse, esa expresión alternativa sólo se ejecutará si la expresión condicional delelseifse evalúa comotrue. Por ejemplo, el siguiente código debe mostrara es mayor que b,a es igual que boa es menor que b:
<?php
if ($a>$b) {
echo"a es mayor que b";
} elseif ($a==$b) {
echo"a es igual que b";
} else {
echo"a es menor que b";
}
?>Puede haber varioselseifdentro de la misma sentenciaif. La primera expresiónelseif(si hay alguna) que se evalúe comotruesería ejecutada. En PHP también se puede escribir 'else if' (en dos palabras) y el comportamiento sería idéntico al de 'elseif' (en una sola palabra). El significado sintáctico es ligeramente diferente (si se está familiarizado con C, este es el mismo comportamiento) pero la conclusión es que ambos resultarían tener exactamente el mismo comportamiento.
La sentenciaelseifes ejecutada solamente si la expresiónifprecedente y cualquiera de las expresioneselseifprecedentes son evaluadas comofalse, y la expresiónelseifactual se evalúa comotrue.
Nota:Tenga en cuenta que
elseifyelse ifserán considerados exactamente iguales sólamente cuando se utilizan llaves como en el ejemplo anterior. Al utilizar los dos puntos para definir las condicionesif/elseif, no debe separarseelse ifen dos palabras o PHP fallará con un error del interprete.
<?php
/* Método incorrecto: */
if ($a>$b):
echo$a." es mayor que ".$b;
else if ($a==$b):// No compilará
echo"La línea anterior provoca un error del interprete.";
endif;
/* Método correcto: */
if ($a>$b):
echo$a." es mayor que ".$b;
elseif ($a==$b):// Tenga en cuenta la combinación de las palabras.
echo$a." igual ".$b;
else:
echo$a." no es ni mayor ni igual a ".$b;
endif;
?>(PHP 4, PHP 5, PHP 7, PHP 8)
PHP ofrece una sintaxis alternativa para algunas de sus estructuras de control, a saber:if,while,for,foreach, yswitch. En cada caso, la forma básica de la sintaxis alternativa es cambiar la llave de apertura por dos puntos (:) y la llave de cierre porendif;,endwhile;,endfor;,endforeach;, oendswitch;, respectivamente.
<?phpif ($a==5):?>
A es igual a 5
<?phpendif;?>En el ejemplo anterior, el bloque HTML "A es igual a 5" está anidado dentro de una sentenciaifescrita en la sintaxis alternativa. El bloque HTML se mostraría solamente si$aes igual a 5.
La sintaxis alternativa también se aplica aelseyelseif. La siguiente es una estructuraifconelseifyelseen el formato alternativo:
<?php
if ($a==5):
echo"a igual 5";
echo"...";
elseif ($a==6):
echo"a igual 6";
echo"!!!";
else:
echo"a no es 5 ni 6";
endif;
?>Nota:
No se admite la mezcla de sintaxis en el mismo bloque de control.
Cualquier salida (incluyendo espacios en blanco) entre una sentenciaswitchy el primercaseresultará en un error de sintaxis. Por ejemplo, esto no es válido:
<?phpswitch ($foo):?>
<?phpcase1:?>
...
<?phpendswitch?>Mientras que lo siguinte es válido, ya que la nueva línea al final después de la sentenciaswitches considerada como parte del?>de cierre, no generando nada entre elswitchy elcase:
<?phpswitch ($foo):?>
<?phpcase1:?>
...
<?phpendswitch?>while(PHP 4, PHP 5, PHP 7, PHP 8)
Los bucleswhileson el tipo más sencillo de bucle en PHP. Se comportan igual que su contrapartida en C. La forma básica de una sentenciawhilees:
while (expr)
sentencia
El significado de una sentenciawhilees simple. Le dice a PHP que ejecute las sentencias anidadas, tanto como la expresiónwhilese evalúe comotrue. El valor de la expresión es verificado cada vez al inicio del bucle, por lo que incluso si este valor cambia durante la ejecución de las sentencias anidadas, la ejecución no se detendrá hasta el final de la iteración (cada vez que PHP ejecuta las sentencias contenidas en el bucle es una iteración). A veces, si la expresiónwhilese evalúa comofalsedesde el principio, las sentencias anidadas no se ejecutarán ni siquiera una vez.
Al igual que con la sentenciaif, se pueden agrupar varias instrucciones dentro del mismo buclewhilerodeando un grupo de sentencias con corchetes, o utilizando la sintaxis alternativa:
while (expr):
sentencias
...
endwhile;
Los siguientes ejemplos son idénticos y ambos presentan los números del 1 al 10:
<?php
/* ejemplo 1 */
$i=1;
while ($i<=10) {
echo$i++;/* el valor presentado sería
$i antes del incremento
(post-incremento) */
}
/* ejemplo 2 */
$i=1;
while ($i<=10):
echo$i;
$i++;
endwhile;
?>do-while(PHP 4, PHP 5, PHP 7, PHP 8)
Los buclesdo-whileson muy similares a los bucleswhile, excepto que la expresión verdadera es verificada al final de cada iteración en lugar que al principio. La diferencia principal con los bucleswhilees que está garantizado que corra la primera iteración de un bucledo-while(la expresión verdadera sólo es verificada al final de la iteración), mientras que no necesariamente va a correr con un buclewhileregular (la expresión verdadera es verificada al principio de cada iteración, si se evalúa comofalsejusto desde el comienzo, la ejecución del bucle terminaría inmediatamente).
Hay una sola sintaxis para buclesdo-while:
<?php
$i=0;
do {
echo$i;
} while ($i>0);
?>El bucle de arriba se ejecutaría exactamente una sola vez, ya que después de la primera iteración, cuando la expresión verdadera es verificada, se evalúa comofalse($ino es mayor que 0) y termina la ejecución del bucle.
Los usuarios avanzados de C pueden estar familiarizados con un uso distinto del bucledo-while, para permitir parar la ejecución en medio de los bloques de código, mediante el encapsulado condo-while(0), y utilizando la sentenciabreak. El siguiente fragmento de código demuestra esto:
<?php
do {
if ($i<5) {
echo"i no es lo suficientemente grande";
break;
}
$i*=$factor;
if ($i<$minimum_limit) {
break;
}
echo"i está bien";
/* procesar i */
} while (0);
?>No se preocupe si no se entiende esto completamente o en absoluto. Se pueden codificar scripts e incluso scripts potentes sin usar esta 'característica'. Desde PHP 5.3.0, es posible utilizar el operadorgotoen lugar de este hack.
for(PHP 4, PHP 5, PHP 7, PHP 8)
Los buclesforson los más complejos en PHP. Se comportan como sus homólogos en C. La sintaxis de un buclefores:
for (expr1; expr2; expr3)
sentencia
La primera expresión (expr1) es evaluada (ejecutada) una vez incondicionalmente al comienzo del bucle.
En el comienzo de cada iteración, se evalúaexpr2. Si se evalúa comotrue, el bucle continúa y se ejecutan la/sy sentencia/s anidada/s. Si se evalúa comofalse, finaliza la ejecución del bucle.
Al final de cada iteración, se evalúa (ejecuta)expr3.
Cada una de las expresiones puede estar vacía o contener múltiples expresiones separadas por comas. Enexpr2, todas las expresiones separadas por una coma son evaluadas, pero el resultado se toma de la última parte. Queexpr2esté vacía significa que el bucle debería ser corrido indefinidamente (PHP implícitamente lo considera comotrue, como en C). Esto puede no ser tan inútil como se pudiera pensar, ya que muchas veces se debe terminar el bucle usando una sentencia condicionalbreaken lugar de utilizar la expresión verdadera delfor.
Considere los siguientes ejemplos. Todos ellos muestran los números del 1 al 10:
<?php
/* ejemplo 1 */
for ($i=1;$i<=10;$i++) {
echo$i;
}
/* ejemplo 2 */
for ($i=1; ;$i++) {
if ($i>10) {
break;
}
echo$i;
}
/* ejemplo 3 */
$i=1;
for (; ; ) {
if ($i>10) {
break;
}
echo$i;
$i++;
}
/* ejemplo 4 */
for ($i=1,$j=0;$i<=10;$j+=$i, print$i,$i++);
?>Por supuesto, el primer ejemplo parece ser el mejor (o quizás el cuarto), pero se puede observar que la posibilidad de usar expresiones vacías en los buclesforresulta útil en muchas ocasiones.
PHP también admite la sintaxis alternativa de los dos puntos para buclesfor.
for (expr1; expr2; expr3):
sentencia
...
endfor;
Es una cosa común a muchos usuarios iterar por medio de arrays como en el siguiente ejemplo.
<?php
/*
* Este es un array con algunos datos que se quieren modificar
* cuando se recorra el bucle for.
*/
$people= array(
array('name'=>'Kalle','salt'=>856412),
array('name'=>'Pierre','salt'=>215863)
);
for($i=0;$i<count($people); ++$i) {
$people[$i]['salt'] =mt_rand(000000,999999);
}
?>El código anterior puede ser lento, debido a que el tamaño del array se capta en cada iteración. Dado que el tamaño nunca cambia, el bucle puede ser fácilmente optimizado mediante el uso de una variable intermedia para almacenar el tamaño en lugar de llamar repetidamente acount():
<?php
$people= array(
array('name'=>'Kalle','salt'=>856412),
array('name'=>'Pierre','salt'=>215863)
);
for($i=0,$size=count($people);$i<$size; ++$i) {
$people[$i]['salt'] =mt_rand(000000,999999);
}
?>foreach(PHP 4, PHP 5, PHP 7, PHP 8)
El constructorforeachproporciona un modo sencillo de iterar sobre arrays.foreachfunciona sólo sobre arrays y objetos, y emitirá un error al intentar usarlo con una variable de un tipo diferente de datos o una variable no inicializada. Existen dos sintaxis:
foreach (expresión_array as $valor)
sentencias
foreach (expresión_array as $clave => $valor)
sentencias
La primera forma recorre el array dado porexpresión_array. En cada iteración, el valor del elemento actual se asigna a$valory el puntero interno del array avanza una posición (así en la próxima iteración se estará observando el siguiente elemento).
La segunda forma además asigna la clave del elemento actual a la variable$claveen cada iteración.
También es posiblepersonalizar la iteración de objetos.
Nota:
En PHP 5, cuando
foreachinicia su ejecución, el puntero interno del array se pone automáticamente en el primer elemento del array. Esto significa que no es necesario llamar la funciónreset()antes de un bucleforeach.Ya que
foreachdepende el puntero de array interno en PHP 5, cambiar éste dentro del bucle puede conducir a un comportamiento inesperado.En PHP 7,
foreachno utiliza el puntero interno del array.
Para poder modificar directamente los elementos del array dentro de bucle, se ha de anteponer & a$valor. En este caso el valor será asignado porreferencia.
<?php
$array= array(1,2,3,4);
foreach ($arrayas &$valor) {
$valor=$valor*2;
}
// $array ahora es array(2, 4, 6, 8)
unset($valor);// rompe la referencia con el último elemento
?>La referencia del$valory el último elemento del array permanecen aún después del bucleforeach. Se recomienda destruirlos conunset(). De lo contrario, se experimentará el siguiente funcionamiento:
<?php
$array= array(1,2,3,4);
foreach ($arrayas &$valor) {
$valor=$valor*2;
}
// $array ahora es array(2, 4, 6, 8)
// sin unset($valor), $valor aún es una referencia al último elemento: $array[3]
foreach ($arrayas$clave=>$valor) {
// $array[3] se actualizará con cada valor de $array...
echo"{$clave}=>{$valor}";
print_r($array);
}
// ...hasta que finalmente el penúltimo valor se copia al último valor
// salida:
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
?>Antes de PHP 5.5.0, referenciar$valorsólo es posible si el array iterado puede ser referenciado (es decir, si es una variable). El siguiente código solamente funciona a partir de PHP 5.5.0:
<?php
foreach (array(1,2,3,4) as &$valor) {
$valor=$valor*2;
}
?>Nota:
foreachno soporta la capacidad de suprimir mensajes de error usando '@'.
Algunos ejemplos más para demostrar su uso:
<?php
/* Ejemplo 1 de foreach: sólo el valor */
$a= array(1,2,3,17);
foreach ($aas$v) {
echo"Valor actual de \$a:$v.\n";
}
/* Ejemplo 2 de foreach: valor (con su notación de acceso manual impreso con fines ilustrativos) */
$a= array(1,2,3,17);
$i=0;/* sólo para efectos ilustrativos */
foreach ($aas$v) {
echo"\$a[$i] =>$v.\n";
$i++;
}
/* Ejemplo 3 de foreach: clave y valor */
$a= array(
"uno"=>1,
"dos"=>2,
"tres"=>3,
"diecisiete"=>17
);
foreach ($aas$k=>$v) {
echo"\$a[$k] =>$v.\n";
}
/* Ejemplo 4 de foreach: arrays multidimensionales */
$a= array();
$a[0][0] ="a";
$a[0][1] ="b";
$a[1][0] ="y";
$a[1][1] ="z";
foreach ($aas$v1) {
foreach ($v1as$v2) {
echo"$v2\n";
}
}
/* Ejemplo 5 de foreach: arrays dinámicos */
foreach (array(1,2,3,4,5) as$v) {
echo"$v\n";
}
?>(PHP 5 >= 5.5.0, PHP 7, PHP 8)
PHP 5.5 añade la posibilidad de recorrer un array de arrays y utilizar el array interior en las variables del bucle proporcionandolist()como el valor.
Por ejemplo:
<?php
$array= [
[1,2],
[3,4],
];
foreach ($arrayas list($a,$b)) {
// $a contiene el primer elemento del array interior,
// y $b contiene el segundo elemento.
echo"A:$a; B:$b\n";
}
?>El resultado del ejemplo sería:
A: 1; B: 2 A: 3; B: 4
Puedes proporcionar menos elementos alist()de los que hay en el array interior, en cuyo caso los elementos sobrantes del array serán descartados:
<?php
$array= [
[1,2],
[3,4],
];
foreach ($arrayas list($a)) {
// Observa que no hay $b en este caso.
echo"$a\n";
}
?>El resultado del ejemplo sería:
1 3
Se generará un notice si no hay suficientes elementos en el array para completar ellist():
<?php
$array= [
[1,2],
[3,4],
];
foreach ($arrayas list($a,$b,$c)) {
echo"A:$a; B:$b; C:$c\n";
}
?>El resultado del ejemplo sería:
Notice: Undefined offset: 2 in example.php on line 7 A: 1; B: 2; C: Notice: Undefined offset: 2 in example.php on line 7 A: 3; B: 4; C:
| Versión | Descripción |
|---|---|
| 7.0.0 | foreachya no utiliza el puntero interno al array. |
| 5.5.0 | Hacer referencia a$valorestá admitido para expresiones. Anteriormente, solamente estaban admitidas las variables. |
| 5.5.0 | El desempaquetamiento de arrays anidados conlist()está admitido. |
break(PHP 4, PHP 5, PHP 7, PHP 8)
breakfinaliza la ejecución de la estructurafor,foreach,while,do-whileoswitchen curso.
breakacepta un argumento numérico opcional que indica de cuántas estructuras anidadas circundantes se debe salir. El valor predeterminado es1, es decir, solamente se sale de la estructura circundante inmediata.
<?php
$arr= array('uno','dos','tres','cuatro','pare','cinco');
while (list(,$val) =each($arr)) {
if ($val=='pare') {
break;/* Se puede también escribir 'break 1;' aquí. */
}
echo"$val<br />\n";
}
/* Utilizar el argumento opcional. */
$i=0;
while (++$i) {
switch ($i) {
case5:
echo"En 5<br />\n";
break1;/* Sólo sale del switch. */
case10:
echo"En 10; saliendo<br />\n";
break2;/* Sale del switch y del while. */
default:
break;
}
}
?>| Versión | Descripción |
|---|---|
| 5.4.0 | break 0;ya no es válido. En versiones anteriores se interpretaba igual quebreak 1;. |
| 5.4.0 | Eliminada la posibilidad de pasar variables (por ejemplo,$num = 2; break $num;) como argumento numérico. |
continue(PHP 4, PHP 5, PHP 7, PHP 8)
continuese utiliza dentro de las estructuras iterativas para saltar el resto de la iteración actual del bucle y continuar la ejecución en la evaluación de la condición, para luego comenzar la siguiente iteración.
Nota:En PHP, la sentenciaswitchse considera una estructura iterativa para los propósitos de
continue.continuese comporta igual quebreak(cuando no se proporcionan argumentos). Si unswitchestá dentro de un bucle,continue 2continurá con la siguiente iteración del bucle externo.
continueacepta un argumento numérico opcional, que indica a cuántos niveles de bucles encerrados se ha de saltar al final. El valor por omisión es1, por lo que salta al final del bucle actual.
<?php
while (list($clave,$valor) =each($arr)) {
if (!($clave%2)) {// saltar los miembros pares
continue;
}
hacer_algo($valor);
}
$i=0;
while ($i++ <5) {
echo"Exterior<br />\n";
while (1) {
echo"Medio<br />\n";
while (1) {
echo"Interior<br />\n";
continue3;
}
echo"Esto nunca se imprimirá.<br />\n";
}
echo"Ni esto tampoco.<br />\n";
}
?>Omitir el punto y coma después delcontinuepuede llevar a confusión. He aquí un ejemplo de lo que no se debe hacer.
<?php
for ($i=0;$i<5; ++$i) {
if ($i==2)
continue
print"$i\n";
}
?>Se esperaría que el resultado fuera:
0 1 3 4
pero, en versiones de PHP anteriores a la 5.4.0, la salida de este script será:
2
debido a quecontinue print "$i\n";se evalúa completo como una sola expresión, y asíprintse llama solamente cuando$i == 2es verdadero. (El valor de retorno deprintes pasado acontinuecomo el argumento numérico.)
Nota:
A partir de PHP 5.4.0, el ejemplo anterior emitirá un error
E_COMPILE_ERROR.
| Versión | Descripción |
|---|---|
| 5.4.0 | continue 0;ya no es válido. En versiones anteriores era interpretado de la misma manera quecontinue 1;. |
| 5.4.0 | Se eliminó la posibilidad de pasar variables (por ejemplo,$num = 2; continue $num;) como el argumento numérico. |
switch(PHP 4, PHP 5, PHP 7, PHP 8)
La sentenciaswitches similar a una serie de sentencias IF en la misma expresión. En muchas ocasiones, es posible que se quiera comparar la misma variable (o expresión) con muchos valores diferentes, y ejecutar una parte de código distinta dependiendo de a que valor es igual. Para esto es exactamente la expresiónswitch.
Nota:Cabe señalar que a diferencia de algunos otros lenguajes, la sentenciacontinuese aplica a
switchy actúa de manera similar abreak. Si se tiene unswitchdentro de un bucle y se desea continuar a la siguiente iteración de del ciclo exterior, se utilizacontinue 2.
Nota:
Tener en cuenta que switch/case hacecomparaciones flexibles.
| Versión | Descripción |
|---|---|
| 7.0.0 | Múltiples casos predeterminados (default) emitirán un error de tipoE_COMPILE_ERROR. |
Los dos ejemplos siguientes son dos formas diferentes de escribir lo mismo, uno con una serie de sentenciasifyelseif, y el otro usando la sentenciaswitch:
Ejemplo #1 Estructuraswitch
<?php
if ($i==0) {
echo"i es igual a 0";
} elseif ($i==1) {
echo"i es igual a 1";
} elseif ($i==2) {
echo"i es igual a 2";
}
switch ($i) {
case0:
echo"i es igual a 0";
break;
case1:
echo"i es igual a 1";
break;
case2:
echo"i es igual a 2";
break;
}
?>Ejemplo #2 Estruturaswitchpermite el uso de strings
<?php
switch ($i) {
case"manzana":
echo"i es una manzana";
break;
case"barra":
echo"i es una barra";
break;
case"pastel":
echo"i es un pastel";
break;
}
?>Es importante entender cómo la sentenciaswitches ejecutada con el fin de evitar errores. La sentenciaswitchejecuta línea por línea (en realidad, sentencia por sentencia). Al principio, ningún código es ejecutado. Solo cuando se encuentra una sentenciacasecuya expresión se evalúa a un valor que coincida con el valor de la con un valor que coincide con el valor de la expresiónswitch, PHP comienza a ejecutar la sentencias. PHP continúa ejecutando las sentencias hasta el final del bloqueswitch, o hasta la primera vez que vea una sentenciabreak. Si no se escribe una sentenciabreakal final de la lista de sentencias de un caso, PHP seguirá ejecutando las sentencias del caso siguiente. Por ejemplo:
<?php
switch ($i) {
case0:
echo"i es igual a 0";
case1:
echo"i es igual a 1";
case2:
echo"i es igual a 2";
}
?>Aquí, si$ies igual a 0, PHP ejecutaría todas las sentencias echo! Si$ies igual a 1, PHP ejecutaría las últimas dos sentencias echo. Se obtendría el comportamiento esperado (se mostraría 'i es igual a 2') sólo si$ies igual a 2. Por lo tanto, es importante no olvidar las sentenciasbreak(aunque es posible que se desee evitar proporcionarlas a propósito bajo determinadas circunstancias).
En una sentenciaswitch, la condición es evaluada sólo una vez y el resultado es comparado con cada una de las sentenciascase. En una sentenciaelseif, la condición es evaluada otra vez. Si la condición es más complicada que una simple comparación y/o está en un bucle estrecho, unswitchpuede ser más rápido.
La lista de sentencias para un caso también puede estar vacía, lo cual simplemente pasa el control a la lista de sentencias para el siguiente caso.
<?php
switch ($i) {
case0:
case1:
case2:
echo"i es menor que 3 pero no negativo";
break;
case3:
echo"i es 3";
}
?>Un caso especial es eldefault. Este caso coincide con cualquier cosa que no se haya correspondido por los otros casos. Por ejemplo:
<?php
switch ($i) {
case0:
echo"i es igual a 0";
break;
case1:
echo"i es igual a 1";
break;
case2:
echo"i es igual a 2";
break;
default:
echo"i no es igual a 0, 1 ni 2";
}
?>La sintaxis alternativa para las estructuras de control es compatible con los switch. Para obtener más información, consulteSintaxis alternativa de estructuras de control.
<?php
switch ($i):
case0:
echo"i es igual a 0";
break;
case1:
echo"i es igual a 1";
break;
case2:
echo"i es igual a 2";
break;
default:
echo"i no es igual a 0, 1 ni 2";
endswitch;
?>Es posible utilizar un punto y coma en lugar de dos puntos después de un caso como:
<?php
switch($beer)
{
case'tuborg';
case'carlsberg';
case'heineken';
echo'Buena elección';
break;
default;
echo'Por favor haga una nueva selección...';
break;
}
?>(PHP 8)
La expresiónmatchramifica la evaluación basada en una comprobación de identidad de un valor. De forma similar a una sentenciaswitch, una expresiónmatchtiene una expresión de sujeto que se compara con múltiples alternativas. A diferencia deswitch, se evaluará a un valor muy parecido al de las expresiones ternarias. A diferencia deswitch, la comparación es una comprobación de identidad (===) en lugar de una comprobación de igualdad débil (==). Las expresiones match están disponibles a partir de PHP 8.0.0.
Ejemplo #1 Estructura de una expresiónmatch
<?php
$return_value=match(subject_expression) {
single_conditional_expression=>return_expression,
conditional_expression1,conditional_expression2=>return_expression,
};
?>Nota:El resultado de una expresión
matchno necesita ser utilizado.
Nota:Una expresión
matchdebeterminar con un punto y coma;.
La expresiónmatches similar a una sentenciaswitchpero tiene algunas diferencias clave:
matchcompara los valores estrictamente (===) en lugar de hacerlo de forma suelta como lo hace la sentencia switch.matchretorna un valor.Matchno pasan a casos posteriores como lo hacen las sentenciasswitch.matchdebe ser completa.Como las expresionesswitch, las expresionesmatchse ejecutan de brazo a brazo. Al principio, no se ejecuta ningún código. Las expresiones condicionales sólo se evalúan si todas las anteriores no coinciden con la expresión del sujeto. Sólo se evaluará la expresión de retorno correspondiente a la expresión condicional que coincida. Por ejemplo:
<?php
$result=match($x) {
foo() => ...,
$this->bar() => ...,// bar() no se llama si foo() === $x
$this->baz=>beep(),// beep() no se llama a menos que $x === $this->baz
// etc.
};
?>Los brazos de la expresiónmatchpueden contener varias expresiones separadas por una coma. Se trata de un OR lógico, y es una abreviatura de múltiples brazos match con el mismo lado derecho.
<?php
$result=match($x) {
// Este brazo match:
$a,$b,$c=>5,
// Es equivalente a estos tres:
$a=>5,
$b=>5,
$c=>5,
};
?>Un caso especial es el patróndefault. Este patrón permite hacer coincidir cualquier cosa que no se haya hecho coincidir previamente. Por ejemplo:
<?php
$expressionResult=match($condition) {
1,2=>foo(),
3,4=>bar(),
default =>baz(),
};
?>Nota:Múltiples patrones default lanzarán un error
E_FATAL_ERROR.
Una expresiónmatchdebe ser completa. Si la expresión del sujeto no es manejada por ningún brazo match se lanza unUnhandledMatchError.
Ejemplo #2 Ejemplo de una expresión match no controlada
<?php
$condition=5;
try {
match($condition) {
1,2=>foo(),
3,4=>bar(),
};
} catch (\UnhandledMatchError $e) {
var_dump($e);
}
?>El resultado del ejemplo sería:
object(UnhandledMatchError)#1 (7) {
["message":protected]=>
string(33) "Unhandled match value of type int"
["string":"Error":private]=>
string(0) ""
["code":protected]=>
int(0)
["file":protected]=>
string(9) "/in/ICgGK"
["line":protected]=>
int(6)
["trace":"Error":private]=>
array(0) {
}
["previous":"Error":private]=>
NULL
}
Es posible utilizar un expresiónmatchpara manejar casos de condicionales de no identidad usandotruecomo expresión del sujeto.
Ejemplo #3 Uso de expresiones match generalizadas para ramificar en rangos de integers
<?php
$age=23;
$result=match(true) {
$age>=65=>'senior',
$age>=25=>'adult',
$age>=18=>'young adult',
default =>'kid',
};
var_dump($result);
?>El resultado del ejemplo sería:
string(11) "young adult"
Ejemplo #4 Uso de expresiones match generalizadas para ramificar el contenido de strings.
<?php
$text='Bienvenue chez nous';
$result=match(true) {
str_contains($text,'Welcome') ||str_contains($text,'Hello') =>'en',
str_contains($text,'Bienvenue') ||str_contains($text,'Bonjour') =>'fr',
// ...
};
var_dump($result);
?>El resultado del ejemplo sería:
string(2) "fr"
declare(PHP 4, PHP 5, PHP 7, PHP 8)
El constructordeclarees usado para fijar directivas de ejecución para un bloque de código. La sintaxis dedeclarees similar a la sintaxis de otros constructores de control de flujo:
declare (directive)
statement
La seccióndirectivepermite que el comportamiento dedeclaresea configurado. Actualmente, solamente están reconocidas tres directivas:ticks(véase abajo para más información sobre la directivaticks),encoding(véase abajo para más información sobre la directivaencoding) ystrict_types(para más infomación, véase la secciónstrictde la página de Argumentos de funciones)
| Versión | Descripción |
|---|---|
| 7.0.0 | Se añadió la directivastrict_types |
| 5.3.0 | Se añadió la directivaencoding |
Ya que las directivas se manejan mientras el fichero está siendo compilado, solamente se pueden proporcionar literales como valores de directivas. No se pueden emplear variables ni constantes. Como ejemplo:
<?php
// Esto es válido:
declare(ticks=1);
// Esto no es válido:
constTICK_VALUE=1;
declare(ticks=TICK_VALUE);
?>La partestatementdel bloquedeclareserá ejecutada - como se ejecuta y que efectos secundarios ocurran durante la ejecución puede depender de la directiva fijada en el bloquedirective.
El constructordeclaretambién se puede utilizar en el alcance global, afectando a todo el código que le sigue (sin embargo, si el archivo con eldeclarefue incluido entonces no afectará al archivo padre).
<?php
// estos son lo mismo:
// se puede usar ésto:
declare(ticks=1) {
// script entero aquí
}
// o se puede usar ésto:
declare(ticks=1);
// script entero aquí
?>Un tick es un evento que ocurre para cada sentencia tickableNde bajo nivel ejecutada por el intérprete dentro del bloquedeclare. El valor paraNse especifica usandoticks=Ndentro del bloque dedeclarede la seccióndirective.
No todas las sentencias son tickable. Por lo general, expresiones de condición y expresiones de argumento no son tickables.
Los eventos que ocurren en cada tick se especifican mediante laregister_tick_function(). Ver el ejemplo abajo para más detalles. Tener en cuenta que más de un evento puede ocurrir por cada tick.
Ejemplo #1 Ejemplo de uso del tick
<?php
declare(ticks=1);
// Una función llamada en cada evento tick
functiontick_handler()
{
echo"tick_handler() llamado\n";
}
register_tick_function('tick_handler');
$a=1;
if ($a>0) {
$a+=2;
print($a);
}
?>Ejemplo #2 Ejemplo de uso de ticks
<?php
functiontick_handler()
{
echo"tick_handler() llamado\n";
}
$a=1;
tick_handler();
if ($a>0) {
$a+=2;
tick_handler();
print($a);
tick_handler();
}
tick_handler();
?>Véase tambiénregister_tick_function()yunregister_tick_function().
Una codificación de script puede ser especificada para cada script usando la directivaencoding.
Ejemplo #3 Declarando un encoding para el script
<?php
declare(encoding='ISO-8859-1');
// código aquí
?>Cuando se combina con espacios de nombres, la única sintaxis legal para declarar esdeclare(encoding='...');donde...es el valor del encoding.declare(encoding='...') {}resultará en un error de análisis cuando se combina con espacios de nombres.
El valor declarado de encoding es ignorado en PHP 5.3 a menos que php esté compilado con--enable-zend-multibyte.
Tener en cuenta que PHP no expone si--enable-zend-multibytefue utilizado para compilar PHP que no sea porphpinfo().
Ver tambiénzend.script_encoding.
(PHP 4, PHP 5, PHP 7, PHP 8)
returndevuelve el control del programa al módulo que lo invoca. La ejecución vuelve a la siguiente expresión después del módulo que lo invoca.
Si se llama desde una función, la sentenciareturninmediatamente termina la ejecución de la función actual, y devuelve su argumento como el valor de la llamada a la función.returntambién termina la ejecución de una sentenciaeval()o un archivo de script.
Si se llama desde el ámbito global, entonces la ejecución del script actual se termina. Si el archivo script actual fue incluido o requerido conincludeorequire, entonces el control es pasado de regreso al archivo que hizo el llamado. Además, si el archivo script actual fue incluido coninclude, entonces el valor dado areturnserá retornado como el valor de la llamadainclude. Sireturnes llamado desde dentro del fichero del script principal, entonces termina la ejecución del script. Si el archivo script actual fue nombrado por las opciones de configuraciónauto_prepend_fileoauto_append_fileenphp.ini, entonces se termina la ejecución de ese archivo script.
Para más información, verRetornando valores.
Nota:Cabe señalar que dado que
returnes un constructor del lenguaje y no una función, los paréntesis que rodean su argumento no son obligatorios y se desaconseja su uso.
Nota:Si no se suministra un parámetro, entonces el paréntesis debe omitirse y
nullserá retornado. Llamadas areturncon paréntesis pero sin argumentos resultarán en un error del intérprete.
(PHP 4, PHP 5, PHP 7, PHP 8)
requirees idéntico aincludeexcepto que en caso de fallo producirá un error fatal de nivelE_COMPILE_ERROR. En otras palabras, éste detiene el script mientras queincludesólo emitirá una advertencia (E_WARNING) lo cual permite continuar el script.
Véase la documentación deincludepara más información.
(PHP 4, PHP 5, PHP 7, PHP 8)
La sentenciaincludeincluye y evalúa el archivo especificado.
La siguiente documentación también se aplica arequire.
Los archivos son incluidos con base en la ruta de acceso dada o, si ninguna es dada, elinclude_pathespecificado. Si el archivo no se encuentra en elinclude_path,includefinalmente verificará en el propio directorio del script que hace el llamado y en el directorio de trabajo actual, antes de fallar. El constructorincludeemitirá unaadvertenciasi no puede encontrar un archivo, éste es un comportamiento diferente al derequire, el cual emitirá unerror fatal..
Si una ruta es definida — ya sea absoluta (comenzando con una letra de unidad o\en Windows o/en sistemas Unix/Linux) o relativa al directorio actual (comenzando con.o..) — elinclude_pathserá ignorado por completo. Por ejemplo, si un nombre de archivo comienza con../, el interprete buscará en el directorio padre para encontrar el archivo solicitado.
Para más información sobre como PHP maneja la inclusión de archivos y la ruta de accesos para incluir, ver la documentación deinclude_path.
Cuando se incluye un archivo, el código que contiene hereda elámbito de las variablesde la línea en la cual ocurre la inclusión. Cualquier variable disponible en esa línea del archivo que hace el llamado, estará disponible en el archivo llamado, desde ese punto en adelante. Sin embargo, todas las funciones y clases definidas en el archivo incluido tienen el ámbito global.
Ejemplo #1 Ejemplo básico deinclude
vars.php
<?php
$color='verde';
$fruta='manzana';
?>
test.php
<?php
echo"Una$fruta$color";// Una
include'vars.php';
echo"Una$fruta$color";// Una manzana verde
?>Si la inclusión ocurre al interior de una función dentro del archivo que hace el llamado, entonces todo el código contenido en el archivo llamado se comportará como si hubiera sido definida dentro de esa función. Por lo tanto, seguirá el ámbito de las variables de esa función. Una excepción a esta regla son lasconstantes mágicaslas cuales son evaluadas por el intérprete antes que ocurra la inclusión.
Ejemplo #2 Incluyendo dentro de funciones
<?php
functionfoo()
{
global$color;
include'vars.php';
echo"Una$fruta$color";
}
/* vars.php está en el ámbito de foo() así que *
* $fruta NO está disponible por fuera de éste *
* ámbito. $color sí está porque fue declarado *
* como global. */
foo();// Una manzana verde
echo"Una$fruta$color";// Una verde
?>Cuando un archivo es incluido, el intérprete abandona el modo PHP e ingresa al modo HTML al comienzo del archivo objetivo y se reanuda de nuevo al final. Por esta razón, cualquier código al interior del archivo objetivo que deba ser ejecutado como código PHP, tendrá que ser encerrado dentro deetiquetas válidas de comienzo y terminación de PHP.
Si las "envolturas URL include" están activadas en PHP, se puede especificar el archivo a ser incluido usando una URL (vía HTTP u otra envoltura soportada - verProtocolos y Envolturas soportadospara una lista de protocolos) en lugar de una ruta de acceso local. Si el servidor objetivo interpreta el archivo objetivo como código PHP, las variables se pueden pasar al archivo incluido usando una string de petición como la usada con HTTP GET. Esto no es, en estricto rigor, lo mismo que haber incluido el archivo y que haya heredado el ámbito de variables del archivo padre; el script realmente está siendo ejecutado en el servidor remoto y el resultado entonces se incluye dentro del script local.
Ejemplo #3includepor medio de HTTP
<?php
/* Este ejemplo asume que www.example.com está configurado para interpretar archivos
* .php y no archivos .txt. Además, aquí 'Funciona' quiere decir que las variables
* $foo y $bar están disponibles dentro del archivo incluido. */
// No funciona; file.txt no puede ser manejado por www.example.com como PHP
include'http://www.example.com/file.txt?foo=1&bar=2';
// No funciona; busca por un archivo llamado 'file.php?foo=1&bar=2' en el
// sistema de archivos local.
include'file.php?foo=1&bar=2';
// Si funciona.
include'http://www.example.com/file.php?foo=1&bar=2';
$foo=1;
$bar=2;
include'file.txt';// Funciona.
include'file.php';// Funciona.
?>El archivo remoto puede ser procesado en el servidor remoto (dependiendo de la extensión del archivo y del hecho de si el servidor remoto corre PHP o no) pero aun así tiene que producir un script PHP válido, porque será procesado en el servidor local. Si el archivo desde el servidor remoto debe ser procesado allá y entregar la salida solamente,readfile()es la mejor función para usar. De lo contrario, debe tenerse especial cuidado para asegurar que el script remoto produce un código válido y deseado.
Ver tambiénArchivos remotos,fopen()yfile()para información relacionada.
Manejando retornos:includedevuelveFALSEen caso de falla y eleva una advertencia. Inclusiones exitosas, a menos que sea reemplazado por el archivo incluido, devolverá1. Es posible ejecutar una sentenciareturndentro de un archivo incluido con el fin de terminar el procesamiento en ese archivo y volver al script que lo llamó. Además, es posible retornar valores desde los archivos incluidos. Se puede tomar el valor de la llamada "include" de la misma forma como se haría con una función normal. Esto no es, sin embargo, posible si se incluyen archivos remotos, a menos que la salida del archivo remoto tenga unasetiquetas válidas de inicio y terminación de PHP(igual que con cualquier archivo local). Se pueden declarar las variables necesarias dentro de esas etiquetas y serán introducidas en cualquiera sea el punto del archivo en el cual fue incluido.
Debido a queincludees un constructor especial del lenguaje, los paréntesis no son necesarios en torno a su argumento. Se debe tener cuidado cuando se compara el valor de retorno.
Ejemplo #4 Comparando el valor de retorno de include
<?php
// no funcionará, se evalúa como include(('vars.php') == TRUE), es decir, include('')
if (include('vars.php') ==TRUE) {
echo'OK';
}
// sí funciona
if ((include'vars.php') ==TRUE) {
echo'OK';
}
?>Ejemplo #5includey la sentenciareturn
return.php
<?php
$var='PHP';
return$var;
?>
noreturn.php
<?php
$var='PHP';
?>
testreturns.php
<?php
$foo= include'return.php';
echo$foo;// muestra 'PHP'
$bar= include'noreturn.php';
echo$bar;// muestra 1
?>$bartiene el valor1debido a que el include fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usareturndentro del archivo incluido, mientras que el otro no. Si el archivo no se pueden incluir, se retornafalsey se emite unE_WARNING.
Si hay funciones definidas en el archivo incluido, se pueden utilizar en el archivo principal independientemente que hayanreturnantes o después. Si el archivo se incluye dos veces, PHP 5 arrojará un error fatal ya que las funciones ya han sido declaradas, mientras que PHP 4 no se queja acerca de las funciones definidas después de unreturn. Se recomienda el uso deinclude_onceen lugar de comprobar si el archivo ya estaba incluido y hacer el retorno de forma condicionada dentro del archivo incluido.
Otra forma de "incluir" un archivo PHP en una variable es capturar la salida mediante el uso deFunciones de control de salidaconinclude. Por ejemplo:
Ejemplo #6 Usando buffering de salida para incluir un archivo PHP dentro de una cadena
<?php
$string=get_include_contents('somefile.php');
functionget_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include$filename;
returnob_get_clean();
}
returnfalse;
}
?>Con el fin de incluir archivos de forma automática dentro de scripts, véase también las opciones de configuraciónauto_prepend_fileandauto_append_fileenphp.ini.
Nota:Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamada usandofunciones variables.
Ver tambiénrequire,require_once,include_once,get_included_files(),readfile(),virtual()yinclude_path.
(PHP 4, PHP 5, PHP 7, PHP 8)
La sentenciarequire_oncees idéntica arequireexcepto que PHP verificará si el archivo ya ha sido incluido y si es así, no se incluye (require) de nuevo.
Ver la documentación deinclude_oncepara información sobre el comportamiento de_once, y como difiere de sus hermanos no_once.
(PHP 4, PHP 5, PHP 7, PHP 8)
La sentenciainclude_onceincluye y evalúa el fichero especificado durante la ejecución del script. Tiene un comportamiento similar al de la sentenciainclude, siendo la única diferencia de que si el código del fichero ya ha sido incluido, no se volverá a incluir, e include_once devolverátrue. Como su nombre indica, el fichero será incluido solamente una vez.
include_oncese puede utilizar en casos donde el mismo fichero podría ser incluido y evaluado más de una vez durante una ejecución particular de un script, así que en este caso, puede ser de ayuda para evitar problemas como la redefinición de funciones, reasignación de valores de variables, etc.
Véase la documentación deincludepara más información sobre cómo funciona esta función.
goto(PHP 5 >= 5.3.0, PHP 7, PHP 8)

El operadorgotopuede ser usado para saltar a otra sección en el programa. El punto de destino es especificado mediante una etiqueta seguida de dos puntos y la instrucción es dada comogotoseguida de la etiqueta del destino deseado. Estegotono es completamente sin restricciones. La etiqueta de destino debe estar dentro del mismo fichero y contexto, lo que significa que no se puede saltar fuera de una función o método, ni se puede saltar dentro de uno. Tampoco se puede saltar dentro de cualquier clase de estructura de bucle o switch. Se puede saltar fuera de estos y un uso común es utilizar ungotoen lugar de unbreakmulti-nivel.
Ejemplo #1 Ejemplo degoto
<?php
gotoa;
echo'Foo';
a:
echo'Bar';
?>El resultado del ejemplo sería:
Bar
Ejemplo #2 Ejemplo degotoen un bucle
<?php
for($i=0,$j=50;$i<100;$i++) {
while($j--) {
if($j==17) gotoend;
}
}
echo"i =$i";
end:
echo'j alcanzó 17';
?>El resultado del ejemplo sería:
j alcanzó 17
Ejemplo #3 Esto no funcionará
<?php
gotoloop;
for($i=0,$j=50;$i<100;$i++) {
while($j--) {
loop:
}
}
echo"$i=$i";
?>El resultado del ejemplo sería:
Fatal error: 'goto' into loop or switch statement is disallowed in script on line 2 (Error fatal: 'goto' hacia el interior de un bucle o sentencia switch no esta permitido en el script en la línea 2)
Nota:
El operador
gotoestá disponible a partir de PHP 5.3.
Una función puede ser definida empleando una sintaxis como la siguiente:
Ejemplo #1 Seudocódigo para demostrar el uso de funciones
<?php
functionfoo($arg_1,$arg_2,/* ..., */$arg_n)
{
echo"Función de ejemplo.\n";
return$valor_devuelto;
}
?>Cualquier código PHP válido puede aparecer dentro de una función, incluso otras funciones y definiciones declases.
Los nombres de las funciones siguen las mismas reglas que las demás etiquetas de PHP. Un nombre de función válido comienza con una letra o guión bajo, seguido de cualquier número de letras, números o guiones bajos. Como expresión regular se expresaría así:^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$.
Vea tambiénGuía de entorno de usuario para nombres.
No es necesario definir una función antes de que sea referenciada,exceptocuando esta esté condicionalmente definida como se muestra en los dos ejemplos de abajo.
Cuando una función está definida de una forma condicional como en los dos ejemplos siguientes, sus definiciones deben ser procesadasantesde ser llamadas.
Ejemplo #2 Funciones condicionales
<?php
$hacer_algo=true;
/* No podemos llamar a foo() desde aquí
ya que no existe aún,
pero podemos llamar a bar() */
bar();
if ($hacer_algo) {
functionfoo()
{
echo"No existo hasta que la ejecución del programa llegue hasta mí.\n";
}
}
/* Ahora podemos llamar de forma segura a foo()
ya que $hacer_algo se evaluó como verdadero */
if ($hacer_algo)foo();
functionbar()
{
echo"Existo desde el momento inmediato que comenzó el programa.\n";
}
?>Ejemplo #3 Funciones dentro de funciones
<?php
functionfoo()
{
functionbar()
{
echo"No existo hasta que se llame a foo().\n";
}
}
/* No podemos llamar aún a bar()
ya que no existe. */
foo();
/* Ahora podemos llamar a bar(),
el procesamiento de foo()
la ha hecho accesible. */
bar();
?>Todas las funciones y clases de PHP tienen ámbito global. Se pueden llamar desde fuera de una función incluso si fueron definidas dentro, y viceversa.
PHP no admite la sobrecarga de funciones, ni es posible 'desdefinir' ni redefinir funciones previamente declaradas.
Nota:Los nombres de las fuciones son insensibles a mayúsculas-minúsculas, aunque es una buena idea llamar a las funciones tal y como aparecen en sus declaraciones.
Las funciones admiten unnúmero variable de argumentosyargumentos predeterminados. Véanse también las referencias de funciones parafunc_num_args(),func_get_arg(), yfunc_get_args()para más información.
En PHP es posible llamar a funciones recursivas.
Ejemplo #4 Funciones recursivas
<?php
functionrecursividad($a)
{
if ($a<20) {
echo"$a\n";
recursividad($a+1);
}
}
?>Nota:Las llamadas a funciones/métodos recursivos con más de 100-200 niveles de recursividad pueden agotar la pila y ocasionar la finalización del script en curso. Especialmente, las recurisvidades infinitas están consideradas un error de programación.
Cualquier información puede ser pasada a las funciones mediante la lista de argumentos, la cual es una lista de expresiones delimitadas por comas. Los argumentos son evaluados de izquierda a derecha.
PHP admite el paso de argumentos por valor (lo predeterminado),el paso por referencia, yvalores de argumentos predeterminados. LasListas de argumentos de longitud variabletambién están soportadas.
Ejemplo #1 Pasar arrays a funciones
<?php
functiontomar_array($entrada)
{
echo"$entrada[0]+$entrada[1]= ".$entrada[0]+$entrada[1];
}
?>Por defecto, los argumentos de las funciones son pasados por valor (así, si el valor del argumento dentro de la función cambia, este no cambia fuera de la función). Para permitir a una función modificar sus argumentos, éstos deben pasarse por referencia.
Para hacer que un argumento a una función sea siempre pasado por referencia hay que anteponer al nombre del argumento el signo 'et' (&) en la definición de la función:
Ejemplo #2 Paso de parámetros de una función por referencia
<?php
functionañadir_algo(&$cadena)
{
$cadena.='y algo más.';
}
$cad='Esto es una cadena, ';
añadir_algo($cad);
echo$cad;// imprime 'Esto es una cadena, y algo más.'
?>Una función puede definir valores predeterminados al estilo de C++ para argumentos escalares como sigue:
Ejemplo #3 Uso de parámetros predeterminados en funciones
<?php
functionhacer_café($tipo="capuchino")
{
return"Hacer una taza de$tipo.\n";
}
echohacer_café();
echohacer_café(null);
echohacer_café("espresso");
?>El resultado del ejemplo sería:
Hacer una taza de capuchino. Hacer una taza de . Hacer una taza de espresso.
PHP también permite el uso dearrays y del tipo especialnullcomo valores predeterminados, por ejemplo:
Ejemplo #4 Usar tipos no escalares como valores predeterminados
<?php
functionhacer_café($tipos= array("capuchino"),$fabricanteCafé=NULL)
{
$aparato=is_null($fabricanteCafé) ?"las manos":$fabricanteCafé;
return"Hacer una taza de ".join(", ",$tipos)." con$aparato.\n";
}
echohacer_café();
echohacer_café(array("capuchino","lavazza"),"una tetera");
?>El valor predeterminado debe ser una expresión constante, no (por ejemplo) una variable, un miembro de una clase o una llamada a una función.
Obsérvese que cuando se emplean argumentos predeterminados, cualquiera de ellos debería estar a la derecha de los argumentos no predeterminados; si no, las cosas no funcionarán como se esperaba. Considérese el siguiente trozo de código:
Ejemplo #5 Uso incorrecto de argumentos predeterminados en una función
<?php
functionhacer_yogur($tipo="acidófilo",$sabor)
{
return"Hacer un tazón de yogur$tipode$sabor.\n";
}
echohacer_yogur("frambuesa");// no funcionará como se esperaba
?>El resultado del ejemplo sería:
Warning: Missing argument 2 in call to hacer_yogur() in /usr/local/etc/httpd/htdocs/phptest/functest.html on line 41 Hacer un tazón de yogur frambuesa de .
Ahora, compare el ejemplo de arriba con este:
Ejemplo #6 Uso correcto de argumentos predeterminados en una función
<?php
functionhacer_yogur($sabor,$tipo="acidófilo")
{
return"Hacer un tazón de yogur$tipode$sabor.\n";
}
echohacer_yogur("frambuesa");// funciona como se esperaba
?>El resultado del ejemplo sería:
Hacer un tazón de yogur acidófilo de frambuensa.
Nota:A partir de PHP 5, los argumentos pasados por referencia pueden tener un valor predeterminado.
Nota:
La declaración de tipos también se conoce como 'Determinación de tipos' en PHP 5.
Las declaraciones de tipo permiten a las funciones requerir que los parámetros sean de cierto tipo durante una llamada. Si el valor dado es de un tipo incorrecto, se generará un error: en PHP 5, este error es un error fatal recuperable, mientras que PHP 7 lanzará una excepciónTypeError.
Para especificar una declaración de tipo, debe anteponerse el nombre del tipo al nombre del parámetro. Se puede hacer que una declaración acepte valoresnullsi el valor predeterminado del parámetro se establece anull.
| Tipo | Descripción | Versión de PHP mínima |
|---|---|---|
| nombre de clase/interfaz | El parámetro debe ser unainstanceofdel nombre de la clase o interfaz dada. | PHP 5.0.0 |
self | El parámetro debe ser unainstanceofde la misma clase donde está definido el método. Esto solamente se puede utilizar en clases y métodos de instancia. | PHP 5.0.0 |
| array | El parámetro debe ser unarray. | PHP 5.1.0 |
| callable | El parámetro debe ser uncallableválido. | PHP 5.4.0 |
| bool | El parámetro debe ser un valor de tipoboolean. | PHP 7.0.0 |
| float | El parámetro debe ser un número de tipofloat. | PHP 7.0.0 |
| int | El parámetro debe ser un valor de tipointeger. | PHP 7.0.0 |
| string | El parámetro debe ser unstring. | PHP 7.0.0 |
iterable | El parámetro debe ser unarrayo unainstanceofTraversable. | PHP 7.1.0 |
object | El parámetro debe ser unobject. | PHP 7.2.0 |
Los alias de los tipos escalares anteriores no están admitidos. En su lugar, son tratados como nombres de clases o de interfaces. Por ejemplo, el empleo debooleancomo parámetro o como tipo devuelto requerirá un argumento o un valor devuelto que sea unaaninstanceofde la clase o interfazboolean, más que el tipobool:
<?php
functionprueba(boolean $param) {}
prueba(true);
?>El resultado del ejemplo sería:
Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
Ejemplo #7 Declaración básica de tipo clase
<?php
classC{}
classDextendsC{}
// Esta no extiende a C.
classE{}
functionf(C $c) {
echoget_class($c)."\n";
}
f(newC);
f(newD);
f(newE);
?>El resultado del ejemplo sería:
C
D
Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
thrown in - on line 8
Ejemplo #8 Declaración básica de tipo interfaz
<?php
interfaceI{ public functionf(); }
classCimplementsI{ public functionf() {} }
// Esta no implementa I.
classE{}
functionf(I $i) {
echoget_class($i)."\n";
}
f(newC);
f(newE);
?>El resultado del ejemplo sería:
C
Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
thrown in - on line 8
Ejemplo #9 Tipos de parámetros pasados por referencia
Los tipos declarados de parámetros de referencia se comprueban en la entrada de la función, pero no cuando la función vuelve, así que después de que la función haya vuelto, el el tipo de argumento puede haber cambiado.
<?php
functionarray_baz(array &$param)
{
$param=1;
}
$var= [];
array_baz($var);
var_dump($var);
array_baz($var);
?>El resultado del ejemplo sería algo similar a:
int(1) Fatal error: Uncaught TypeError: Argument 1 passed to array_baz() must be of the type array, int given, called in %s on line %d
Ejemplo #10 Declaración de tipo nulo
<?php
classC{}
functionf(C $c=null) {
var_dump($c);
}
f(newC);
f(null);
?>El resultado del ejemplo sería:
object(C)#1 (0) {
}
NULL
Por defecto, PHP fuerza a los valores de un tipo erróneo a ser del tipo escalar esperado si es posible. Por ejemplo, una función a la que se le pasa unintegerpara un parámetro que se prevé sea unstringobtendrá una variable de tipostring.
Es posible habilitar el modo estricto en función de cada fichero. El el modo estricto solamente será aceptada una variable del tipo exacto de la declaración de tipo, o será lanzada unaTypeError. La única excepción a esta regla es que se podría proporcionar unintegera una función que espere unfloat. Las llamadas a funciones desde dentro de funciones internas no se verán afectadas por la declaraciónstrict_types.
Para habilitar el modo escricto se emplea la sentenciadeclarecon la declaraciónstrict_types:
Habilitar el modo esctricto también afectará a lasdeclaraciones de tipo de devolución.
Nota:
La tipificación estricta se aplica a las llamadas a funciones hechas desdedentrodel fichero con la tipificación estricta habilitada, no a las funciones declaradas dentro del fichero. Si un fichero sin la tipificación estricta habilitada realiza una llamada a una función definida en un fichero con tipificación estricta, será respetada la preferencia del llamador (tipificación débil), y se forzará el valor.
Nota:
La tipificación estricta solamente se define para declaraciones de tipos escalares, y como tal, requiere PHP 7.0.0 o posterior, ya que las declaraciones de tipo escalar fueron añadidas en esta versión.
Ejemplo #11 Tipificación estricta
<?php
declare(strict_types=1);
functionsum(int $a,int $b) {
return$a+$b;
}
var_dump(sum(1,2));
var_dump(sum(1.5,2.5));
?>El resultado del ejemplo sería:
int(3)
Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
thrown in - on line 4
Ejemplo #12 Tipificación débil
<?php
functionsum(int $a,int $b) {
return$a+$b;
}
var_dump(sum(1,2));
// Estos números serán forzados a ser enteros: ¡observe la salida de abajo!
var_dump(sum(1.5,2.5));
?>El resultado del ejemplo sería:
int(3) int(3)
Ejemplo #13 Capturar la excepciónTypeError
<?php
declare(strict_types=1);
functionsum(int $a,int $b) {
return$a+$b;
}
try {
var_dump(sum(1,2));
var_dump(sum(1.5,2.5));
} catch (TypeError $e) {
echo'Error: '.$e->getMessage();
}
?>El resultado del ejemplo sería:
int(3) Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10
PHP tiene soporte para listas de argumentos de longitud variable en funciones definidas por el usuario. Esto se implementa utilizando el token...en PHP 5.6 y posteriores, y utilizando las funcionesfunc_num_args(),func_get_arg(), yfunc_get_args()en PHP 5.5 y anteriores.
...en PHP 5.6+En PHP 5.6 y posteriores, las listas de argumentos pueden incluir el token...para denotar que la función acepta un número variable de argumentos. Los argumentos serán pasados a la variable dada como un aryay, por ejemplo:
Ejemplo #14 Usando...para acceder a argumentos variables
<?php
functionsum(...$números) {
$acc=0;
foreach ($númerosas$n) {
$acc+=$n;
}
return$acc;
}
echosum(1,2,3,4);
?>El resultado del ejemplo sería:
10
También se puede emplear...al llamar a funciones para convertir unarrayo variableTraversableo literal en una lista de argumentos:
Ejemplo #15 Usar...para proporcionar argumentos
<?php
functionadd($a,$b) {
return$a+$b;
}
echoadd(...[1,2])."\n";
$a= [1,2];
echoadd(...$a);
?>El resultado del ejemplo sería:
3 3
Se puede especifcar argumentos posicionales normales antes del token.... En este caso, solamente los argumentos al final que no coincidan con un argumento posicional serán añadidos al array generado por....
También es posible añadir unadeclaración de tipoantes del símbolo.... Si está presente, todos los argumentos capturados por...deben ser objetos de la clase implicada.
Ejemplo #16 Argumentos variables de declaración de tipo
<?php
functiontotal_intervals($unit,DateInterval...$intervals) {
$time=0;
foreach ($intervalsas$interval) {
$time+=$interval->$unit;
}
return$time;
}
$a= newDateInterval('P1D');
$b= newDateInterval('P2D');
echototal_intervals('d',$a,$b).' days';
// Esto fallará, debido a que null no es un objeto de DateInterval.
echototal_intervals('d',null);
?>El resultado del ejemplo sería:
3 days Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2
Por último, también es pueden pasar argumentos variablespor referenciaprefijando...con el signo (&).
No se requiere una sintaxis especial para señalar que una función es varíadica; sin embargo, para acceder a los argumentos de la función se debe usarfunc_num_args(),func_get_arg()yfunc_get_args().
El primer ejemplo de antes se implementaría en PHP 5.5 y anteriores como sigue:
Ejemplo #17 Acceder a argumentos variables en PHP 5.5 y anteriores
<?php
functionsum() {
$acc=0;
foreach (func_get_args() as$n) {
$acc+=$n;
}
return$acc;
}
echosum(1,2,3,4);
?>El resultado del ejemplo sería:
10
PHP 8.0.0 introduced named arguments as an extension of the existing positional parameters. Named arguments allow passing arguments to a function based on the parameter name, rather than the parameter position. This makes the meaning of the argument self-documenting, makes the arguments order-independent and allows skipping default values arbitrarily.
Named arguments are passed by prefixing the value with the parameter name followed by a colon. Using reserved keywords as parameter names is allowed. The parameter name must be an identifier, specifying dynamically is not allowed.
Ejemplo #18 Named argument syntax
<?php
myFunction(paramName:$value);
array_foobar(array:$value);
// NOT supported.
function_name($variableStoringParamName:$value);
?>Ejemplo #19 Positional arguments versus named arguments
<?php
// Using positional arguments:
array_fill(0,100,50);
// Using named arguments:
array_fill(start_index:0,count:100,value:50);
?>The order in which the named arguments are passed does not matter.
Ejemplo #20 Same example as above with a different order of parameters
<?php
array_fill(value:50,num:100,start_index:0);
?>Named arguments can be combined with positional arguments. In this case, the named arguments must come after the positional arguments. It is also possible to specify only some of the optional arguments of a function, regardless of their order.
Ejemplo #21 Combining named arguments with positional arguments
<?php
htmlspecialchars($string,double_encode:false);
// Same as
htmlspecialchars($string,ENT_COMPAT|ENT_HTML401,'UTF-8',false);
?>Passing the same parameter multiple times results in an Error exception.
Ejemplo #22 Error exception when passing the same parameter multiple times
<?php
functionfoo($param) { ... }
foo(param:1,param:2);
// Error: Named parameter $param overwrites previous argument
foo(1,param:2);
// Error: Named parameter $param overwrites previous argument
?>Los valores son devueltos usando la sentencia opcional return. Se puede devolver cualquier tipo, incluidos arrays y objetos. Esto causa que la función finalice su ejecución inmediatamente y pase el control de nuevo a la línea desde la que fue llamada. Véasereturnpara más información.
Nota:
Si se omitereturn, el valor devuelto será
null.
Ejemplo #1 Empleo dereturn
<?php
functioncuadrado($núm)
{
return$núm*$núm;
}
echocuadrado(4);// imprime '16'.
?>Una función no puede devolver múltiples valores, pero se pueden obtener resultados similares devolviendo un array.
Ejemplo #2 Devolver un array para obtener múltiples valores
<?php
functionnúmeros_pequeños()
{
return array (0,1,2);
}
list ($cero,$uno,$dos) =números_pequeños();
?>Para devolver una referencia desde una función use el operador de referencia &, en la declaración de la función y cuando se asigne el valor devuelto a una variable:
Ejemplo #3 Devolver una referencia desde una función
<?php
function &devolver_referencia()
{
return$algunaref;
}
$nuevaref=&devolver_referencia();
?>Para más información sobre referencias, por favor, lea lasReferencias explicadas.
PHP 7 añade soporte para las declaraciones de tipo de devolución. De forma similar a lasdeclaraciones de tipo de argumento, las declaraciones de tipo de devolución especifican el tipo del valor que serán devuelto desde una función. Están disponibles los mismostipospara las declaraciones de tipo de devolución que para las declaraciones de tipo de argumento.
Latipificación estrictatambién tiene efecto sobre las declaraciones de tipo de devolución. En el modo predeterminado de tipificacón débil, los valores devueltos serán forzados al tipo correcto si no son ya de ese tipo. En el modo fuerte, el valor devuelto debe ser del tipo correcto, o de lo contrario se lanzará una excepciónTypeError.
A partir de PHP 7.1.0, los valores de retorno pueden ser marcados como anulables anteponiendo el prefijo nombre de tipo con un signo de interrogación (?). Esto significa que la función devuelve el tipo especificado onull.
Nota:
Al sobrescribir un método padre, el método hijo debe hacer coincidir cualquier declaración de tipo de devolución del padre. Si el padre no define un tipo de devolución, el método hijo puede hacerlo.
Ejemplo #4 Declaración básica de tipo de devolución
<?php
functionsum($a,$b):float{
return$a+$b;
}
// Observe que será devuelto un float.
var_dump(sum(1,2));
?>El resultado del ejemplo sería:
float(3)
Ejemplo #5 El modo estricto en acción
<?php
declare(strict_types=1);
functionsum($a,$b):int{
return$a+$b;
}
var_dump(sum(1,2));
var_dump(sum(1,2.5));
?>El resultado del ejemplo sería:
int(3)
Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
thrown in - on line 5
Ejemplo #6 Devolver un objeto
<?php
classC{}
functiongetC():C{
return newC;
}
var_dump(getC());
?>El resultado del ejemplo sería:
object(C)#1 (0) {
}
Ejemplo #7 Declaración de tipo de retorno anulable (a partir de PHP 7.1.0)
<?php
functionget_item(): ?string{
if (isset($_GET['item'])) {
return$_GET['item'];
} else {
returnnull;
}
}
?>PHP admite el concepto de funciones variables. Esto significa que si un nombre de variable tiene paréntesis anexos a él, PHP buscará una función con el mismo nombre que lo evaluado por la variable, e intentará ejecutarla. Entre otras cosas, esto se puede usar para implementar llamadas de retorno, tablas de funciones, y así sucesivamente.
Las funciones variables no funcionarán con constructores de lenguaje comoecho,print,unset(),isset(),empty(),include,requirey similares. Utilice funciones de envoltura para hacer uso de cualquiera de estos constructores como funciones variables.
Ejemplo #1 Ejemplo de función variable
<?php
functionfoo() {
echo"En foo()<br />\n";
}
functionbar($arg='')
{
echo"En bar(); el argumento era '$arg'.<br />\n";
}
// Esta es una función de envoltura alrededor de echo
functionhacerecho($cadena)
{
echo$cadena;
}
$func='foo';
$func();// Esto llama a foo()
$func='bar';
$func('prueba');// Esto llama a bar()
$func='hacerecho';
$func('prueba');// Esto llama a hacerecho()
?>Los métodos de objetos también puede ser llamados con la sintaxis de funciones variables.
Ejemplo #2 Ejemplo de método variable
<?php
classFoo
{
functionVariable()
{
$nombre='Bar';
$this->$nombre();// Esto llama al método Bar()
}
functionBar()
{
echo"Esto es Bar";
}
}
$foo= newFoo();
$nombrefunc="Variable";
$foo->$nombrefunc();// Esto llama a $foo->Variable()
?>Cuando se llaman a métodos estáticos, la llamada a la función es más fuerte que el operador de propiedad estática:
Ejemplo #3 Ejemplo de método variable con propiedades estáticas
<?php
classFoo
{
static$variable='propiedad estática';
static functionVariable()
{
echo'Método Variable llamado';
}
}
echoFoo::$variable;// Esto imprime 'propiedad estática'. No necesita una $variable en este ámbito.
$variable="Variable";
Foo::$variable();// Esto llama a $foo->Variable() leyendo $variable en este ámbito.
?>A partir de PHP 5.4.0, se puede llamar a cualquiercallablealmacenado en una variable.
Ejemplo #4 Llamables complejos
<?php
classFoo
{
static functionbar()
{
echo"bar\n";
}
functionbaz()
{
echo"baz\n";
}
}
$func= array("Foo","bar");
$func();// imprime "bar"
$func= array(newFoo,"baz");
$func();// imprime "baz"
$func="Foo::bar";
$func();// imprime "bar" a partrid de PHP 7.0.0; antes, emitía un error fatal
?>Véase tambiénis_callable(),call_user_func(),variables variablesyfunction_exists().
| Versión | Descripción |
|---|---|
| 7.0.0 | 'NombreDeClase::NombreDeMétodo' se permite como función variable. |
| 5.4.0 | Los arrays, que son llamables válidos, están permitidos como funciones variables. |
PHP se estandariza con muchas funciones y construcciones. También existen funciones que necesitan extensiones específicas de PHP compiladas, si no, aparecerán errores fatales "undefined function" ("función no definida"). Por ejemplo, para usar las funciones deimagetales comoimagecreatetruecolor(), PHP debe ser compilado con soporte paraGD. O para usarmysql_connect(), PHP debe ser compilado con soporte paraMySQLi. Hay muchas funciones de núcleo que está incluidas en cada versión de PHP, tales como las funciones destringy devariable. Una llamada aphpinfo()oget_loaded_extensions()mostrará las extensiones que están cargadas en PHP. Observe también que muchas extensiones están habilitadas por defecto y que el manual de PHP está dividido por extensiones. Véaseconfiguración,instalación, y capítulos individuales de extensiones para más información sobre cómo configurar PHP.
Interpretar y comprender un prototipo de una función está explicado dentro de la sección del manual tituladacómo interpretar la definición de una función. Es importante comprender lo que devuelve una función o si una función funciona directamente con un valor pasado. Por ejemplo,str_replace()devolverá la cadena modificada mientras queusort()funciona con la variable actual pasada. Cada página del manual también tiene información específica para cada función, como información sobre parámetros de funciones, cambios de comportamiento, valores devueltos en caso de éxito o fallo, e información de disponibilidad. Conocer estas importantes diferencias (a menudo imperceptibles) es crucial para escribir código de PHP correcto.
Nota:Si los parámetros dados a una función no son los que se esperaban, como pasar unarraydonde se esperaba unstring, el valor devuelto de la función será indefinido. En este caso lo más probable es que devuelva
nullpero esto es sólo una convención, y no se puede confiar en ello.
Véase tambiénfunction_exists(),la referencia de funciones,get_extension_funcs(), ydl().
Las funciones anónimas, también conocidas comocierres(closures), permiten la creación de funciones que no tienen un nombre especificado. Son más útiles como valor de los parámetros dellamadas de retorno, pero tienen muchos otros usos.
Las funciones anónimas están implementadas utilizando la claseClosure.
Ejemplo #1 Ejemplo de función anónima
<?php
echopreg_replace_callback('~-([a-z])~', function ($coincidencia) {
returnstrtoupper($coincidencia[1]);
},'hola-mundo');
// imprime holaMundo
?>Los cierres también se pueden usar como valores de variables; PHP automáticamente convierte tales expresiones en instancias de la clase internaClosure. La asignación de un cierre a una variable emplea la misma sintaxis que cualquier otra asignación, incluido el punto y coma final:
Ejemplo #2 Ejemplo de asignación de variable de una función anónima
<?php
$saludo= function($nombre)
{
printf("Hola %s\r\n",$nombre);
};
$saludo('Mundo');
$saludo('PHP');
?>Los cierres también pueden heredar variables del ámbito padre. Cualquier variable debe ser pasada al constructor de lenguajeuse. Desde PHP 7.1, estas variables no deben incluirsuperglobals,$this, o variables con el mismo nombre que un parámetro.
Ejemplo #3 Heredar variables de un ámbito padre
<?php
$mensaje='hola';
// Sin "use"
$ejemplo= function () {
var_dump($mensaje);
};
$ejemplo();
// Heredar $mensaje
$ejemplo= function () use ($mensaje) {
var_dump($mensaje);
};
$ejemplo();
// El valor de la variable heredada está cuando la función
// está definida, no cuando se le invoca
$mensaje='mundo';
$ejemplo();
// Reiniciar el mensaje
$mensaje='hola';
// Heredar por referencia
$ejemplo= function () use (&$mensaje) {
var_dump($mensaje);
};
$ejemplo();
// El valor cambiado en el ámbito padre
// se refleja dentro de la llamada a la función
$mensaje='mundo';
$ejemplo();
// Los cierres también aceptan argumentos normales
$ejemplo= function ($arg) use ($mensaje) {
var_dump($arg.' '.$mensaje);
};
$ejemplo("hola");
?>El resultado del ejemplo sería algo similar a:
Notice: Undefined variable: message in /example.php on line 6 NULL string(4) "hola" string(4) "hola" string(4) "hola" string(5) "mundo" string(10) "hola mundo"
Heredar variables del ámbito padrenoes lo mismo que usar variables globales. Las variables globales existen en el ámbito global, lo que implica que no importa qué función se esté ejecutando. El ámbito padre de un cierre es la función en la que dicho cierre fue declarado (no necesariamente la función desde la que se llamó). Vea el siguiente ejemplo:
Ejemplo #4 Cierres y ámbito
<?php
// Un carro de compras básico que contiene una lista de productos añadidos
// y la cantidad de cada producto. Incluye un método que
// calcula el precio total de los artículos del carro usando un
// cierre como llamada de retorno.
classCarro
{
constPRECIO_MANTEQUILLA=1.00;
constPRECIO_LECHE=3.00;
constPRECIO_HUEVOS=6.95;
protected$productos= array();
public functionañadir($producto,$cantidad)
{
$this->productos[$producto] =$cantidad;
}
public functionobtenerCantidad($producto)
{
return isset($this->productos[$producto]) ?$this->productos[$producto] :
FALSE;
}
public functionobtenerTotal($impuesto)
{
$total=0.00;
$llamadaDeRetorno=
function ($cantidad,$producto) use ($impuesto, &$total)
{
$precioUnidad=constant(__CLASS__."::PRECIO_".
strtoupper($producto));
$total+= ($precioUnidad*$cantidad) * ($impuesto+1.0);
};
array_walk($this->productos,$llamadaDeRetorno);
returnround($total,2);
}
}
$mi_carro= newCarro;
// Añadir algunos artículos al carro
$mi_carro->añadir('mantequilla',1);
$mi_carro->añadir('leche',3);
$mi_carro->añadir('huevos',6);
// Imprimir el total con un impuesto de venta del 5%.
print$mi_carro->obtenerTotal(0.05) ."\n";
// El resultado es 54.29
?>Ejemplo #5 Vinculación automática de$this
<?php
classTest
{
public functiontesting()
{
return function() {
var_dump($this);
};
}
}
$object= newTest;
$function=$object->testing();
$function();
?>El resultado del ejemplo sería:
object(Test)#1 (0) {
}
Salida del ejemplo anterior en PHP 5.3:
Notice: Undefined variable: this in script.php on line 8 NULL
A partir de PHP 5.4.0, cuando se declara en el contexto de una clase, la clase actual está vinculada a ella automáticamente, haciendo que$thisesté disponible dentro del ámbito de la función. Si no se desea esta vinculación automática de la clase actual, se deberían usarfuncions anónimas estáticasen su lugar.
A partir de PHP 5.4, las funciones anónimas pueden ser declaradas estáticamente. Esto evita tener la clase actual vinculada automáticamente a ellas. Los objetos tampoco podrían vincularse a ellas durante la ejecución.
Ejemplo #6 Intentar usar$thisdentro de una función anónima estática
<?php
classFoo
{
function__construct()
{
$func= static function() {
var_dump($this);
};
$func();
}
};
newFoo();
?>El resultado del ejemplo sería:
Notice: Undefined variable: this in %s on line %d NULL
Ejemplo #7 Intentar vincular un objeto a una función anónima estática
<?php
$func= static function() {
// cuerpo de la función
};
$func=$func->bindTo(newStdClass);
$func();
?>El resultado del ejemplo sería:
Warning: Cannot bind an instance to a static closure in %s on line %d
| Versión | Descripción |
|---|---|
| 7.1.0 | Las funciones anónimas no pueden tener un cierre sobresuperglobals,$this, o cualquier variable con el mismo nombre que un parámetro. |
| 5.4.0 | Las funciones anónimas pueden usar$this, así como ser declaradas státicamente. |
| 5.3.0 | Las funciones anónimas se encuentran disponibles. |
Nota:Es posible utilizarfunc_num_args(),func_get_arg(), yfunc_get_args()desde dentro de un cierre.
Las funciones de flecha fueron introducidas en PHP 7.4 como una sintaxis más concisa paralas funciones anónimas.
Tanto las funciones anónimas como las funciones de flecha se implementan utilizando la claseClosure.
Las funciones de las flechas tienen la forma básicafn (argument_list) => expr.
Las funciones de las flechas soportan las mismas características quelas funciones anónimas, excepto que el uso de variables del ámbito padre siempre es automático.
Cuando una variable utilizada en la expresión se define en el ámbito padre será implícitamente capturada por valor. En el siguiente ejemplo, las funciones$fn1y$fn2se comportan de la misma manera.
Ejemplo #1 Las funciones de flecha capturan las variables por valor automáticamente
<?php
$y=1;
$fn1=fn($x) =>$x+$y;
// equivalent to using $y by value:
$fn2= function ($x) use ($y) {
return$x+$y;
};
var_export($fn1(3));
?>El resultado del ejemplo sería:
4
Esto también funciona si las funciones de la flecha están anidadas:
Ejemplo #2 Las funciones de flecha capturan variables por valor automáticamente, incluso cuando están anidadas
<?php
$z=1;
$fn=fn($x) =>fn($y) =>$x*$y+$z;
// Outputs 51
var_export($fn(5)(10));
?>De manera similar a las funciones anónimas, la sintaxis de la función de la flecha permite firmas de funciones arbitrarias, incluyendo los tipos de parámetros y de retorno, valores por defecto, variadades, así como por referencia al pasar y al regresar. Todos los siguientes son ejemplos válidos de las funciones de las flechas:
Ejemplo #3 Ejemplos de funciones de flecha
<?php
fn(array$x) =>$x;
staticfn():int=>$x;
fn($x=42) =>$x;
fn(&$x) =>$x;
fn&($x) =>$x;
fn($x, ...$rest) =>$rest;
?>Las funciones de flecha utilizan la unión variable por valor. Esto es aproximadamente equivalente a realizar unuse($x)para cada variable$xusada dentro de la función de la flecha. Una unión por valores significa que no es posible modificar ningún valor desde el ámbito exterior.Funciones anónimasse pueden utilizar en su lugar para las asignaciones por referencia.
Ejemplo #4 Los valores del alcance exterior no pueden ser modificados por las funciones de flecha
<?php
$x=1;
$fn=fn() =>$x++;// No tiene ningún efecto
$fn();
var_export($x);// Salida 1
?>| Versión | Descripción |
|---|---|
| 7.4.0 | Las funciones de flecha se hicieron disponibles. |
Nota:Es posible utilizarfunc_num_args(),func_get_arg(), yfunc_get_args()desde dentro de una función de flecha.
PHP incluye un modelo de objetos completo. Algunas de sus características son:visibilidad, clases y métodosabstractosyfinales,métodos mágicosadicionales,interfaces,clonación.
PHP trata los objetos de la misma manera que las referencias o manejadores, lo que significa que cada variable contiene una referencia a un objeto en lugar de una copia de todo el objeto. Véanse losObjetos y referencias
Vea tambiénGuía de entorno de usuario para nombres.
La definición básica de una clase comienza con la palabra reservadaclass, seguida de un nombre de clase, y continuando con un par de llaves que encierran las definiciones de las propiedades y métodos pertenecientes a dicha clase.
El nombre de clase puede ser cualquier etiqueta válida, siempre que no sea unapalabra reservadade PHP. Un nombre válido de clase comienza con una letra o un guión bajo, seguido de una cantidad arbitraria de letras, números o guiones bajos. Como expresión regular, se expresaría de la siguiente forma:^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$.
Una clase puede tener sus propiasconstantes,variables(llamadas "propiedades"), y funciones (llamados "métodos").
Ejemplo #1 Definición de una clase sencilla
<?php
classClaseSencilla
{
// Declaración de una propiedad
public$var='un valor predeterminado';
// Declaración de un método
public functionmostrarVar() {
echo$this->var;
}
}
?>La pseudovariable$thisestá disponible cuando un método es invocado dentro del contexto de un objeto.$thises una referencia al objeto invocador.
Llamar a un método no estático arroja estáticamente unError. Antes de PHP 8.0.0, esto generaría un aviso de desaprobación obsoleta, y$thisesto no estaría definido.
Ejemplo #2 Algunos ejemplos de la pseudovariable$this
<?php
classA
{
functionfoo()
{
if (isset($this)) {
echo'$this está definida (';
echoget_class($this);
echo")\n";
} else {
echo"\$this no está definida.\n";
}
}
}
classB
{
functionbar()
{
A::foo();
}
}
$a= newA();
$a->foo();
A::foo();
$b= newB();
$b->bar();
B::bar();
?>Salida del ejemplo anterior en PHP 7:
$this está definida (A) Deprecated: Non-static method A::foo() should not be called statically in %s on line 27 $this is not defined. Deprecated: Non-static method A::foo() should not be called statically in %s on line 20 $this is not defined. Deprecated: Non-static method B::bar() should not be called statically in %s on line 32 Deprecated: Non-static method A::foo() should not be called statically in %s on line 20 $this is not defined.
Output of the above example in PHP 8:
$this está definida (A)
Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
Stack trace:
#0 {main}
thrown in %s on line 27
As of PHP 8.2.0, a class can be marked with thereadonlymodifier. Marking a class asreadonlywill add thereadonlymodifierto every declared property, and prevent the creation ofdynamic properties. Moreover, it is impossible to add support for them by using theAllowDynamicPropertiesattribute. Attempting to do so will trigger a compile-time error.
<?php
#[AllowDynamicProperties]
readonlyclassFoo{
}
// Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
?>As neither untyped, nor static properties can be marked with thereadonlymodifier, readonly classes cannot declare them either:
<?php
readonlyclassFoo
{
public$bar;
}
// Fatal error: Readonly property Foo::$bar must have type
?><?php
readonlyclassFoo
{
public staticint $bar;
}
// Fatal error: Readonly class Foo cannot declare static properties
?>Areadonlyclass can beextendedif, and only if, the child class is also areadonlyclass.
Para crear una instancia de una clase, se debe emplear la palabra reservadanew. Un objeto se creará siempre a menos que el objeto tenga unconstructorque arroje unaexcepciónen caso de error. Las clases deberían ser definidas antes de la instanciación (y en algunos casos esto es un requerimiento).
Si se emplea unstringque contenga el nombre de una clase connew, se creará una nueva instancia de esa clase. Si la clase estuviera en un espacio de nombres, se debe utilizar su nombre completo al realizar esto.
Nota:
Si no hay argumentos para pasar al constructor de la clase, se pueden omitir los paréntesis después del nombre de la clase.
Ejemplo #3 Creación de una instancia
<?php
$instancia= newClaseSencilla();
// Esto también se puede hacer con una variable:
$nombreClase='ClaseSencilla';
$instancia= new$nombreClase();// new ClaseSencilla()
?>En el contexto de una clase, es posible crear un nuevo objeto connew selfynew parent.
Cuando se asigna una instancia ya creada de una clase a una nueva variable, ésta última accederá a la misma instancia que el objeto que le fue asignado. Esta conducta es la misma que cuando se pasan instancias a una función. Se puede realizar una copia de un objeto ya creado a través de laclonacióndel mismo.
Ejemplo #4 Asignación de objetos
<?php
$instancia= newClaseSencilla();
$asignada=$instancia;
$referencia=&$instancia;
$instancia->var='$asignada tendrá este valor';
$instancia=null;// $instancia y $referencia son null
var_dump($instancia);
var_dump($referencia);
var_dump($asignada);
?>El resultado del ejemplo sería:
NULL
NULL
object(ClaseSencilla)#1 (1) {
["var"]=>
string(27) "$asignada tendrá este valor"
}
Existe un par de formas de crear instancias de un objecto:
Ejemplo #5 Creación de nuevos objetos
<?php
classPrueba
{
static public functiongetNew()
{
return new static;
}
}
classHijaextendsPrueba
{}
$obj1= newPrueba();
$obj2= new$obj1;
var_dump($obj1!==$obj2);
$obj3=Prueba::getNew();
var_dump($obj3instanceofPrueba);
$obj4=Hija::getNew();
var_dump($obj4instanceofHija);
?>El resultado del ejemplo sería:
bool(true) bool(true) bool(true)
Es posible acceder a un miembro de un objeto recién creado en una única expresión:
Ejemplo #6 Acceder a un miembro de un objeto recién creado
<?php
echo (newDateTime())->format('Y');
?>El resultado del ejemplo sería algo similar a:
2016
Nota:Antes de PHP 7.1, los argumentos no se evalúan si no hay una función constructora definida.
Las propiedades y métodos de una clase viven en «espacios de nombres» diferentes, por tanto, es posible tener una propiedad y un método con el mismo nombre. Al hacer referencia tanto a una propiedad como a un método se utiliza la misma notación, y si se accederá a la propiedad o se llamará al método, solamente depende del contexto, es decir, si el empleo es el acceso a una variable o la llamada a una función.
Ejemplo #7 Acceso a propiedad contra llamada a método
<?php
classFoo
{
public$bar='property';
public functionbar() {
return'method';
}
}
$obj= newFoo();
echo$obj->bar,PHP_EOL,$obj->bar(),PHP_EOL;El resultado del ejemplo sería:
propiedad método
Esto significa que llamar a unafunción anónimaque ha sido asignada a una propiedad no es posible directamente. En su lugar, la propiedad ha de ser asignada primero a una variable, por ejemplo. A partir de PHP 7.0.0, es posible llamar a dicha propiedad directamente encerrándola entre paréntesis.
Ejemplo #8 Llamar a una función anónima almacenada en una propiedad
<?php
classFoo
{
public$bar;
public function__construct() {
$this->bar= function() {
return42;
};
}
}
$obj= newFoo();
echo ($obj->bar)(),PHP_EOL;El resultado del ejemplo sería:
42
Una clase puede heredar los métodos y propiedades de otra clase empleando la palabra reservadaextendsen la declaración de la clase. No es posible la extensión de múltiples clases; una clase sólo puede heredar de una clase base.
Los métodos y propiedades heredados pueden ser sobrescritos con la redeclaración de éstos utilizando el mismo nombre que en la clase madre. Sin embargo, si la clase madre definió un método comofinal, éste no podrá ser sobrescrito. Es posible acceder a los métodos sobrescritos o a las propiedades estáticas haciendo referencia a ellos conparent::.
Ejemplo #9 Herencia de clases sencilla
<?php
classClaseExtendidaextendsClaseSencilla
{
// Redefinición del método padre
functionmostrarVar()
{
echo"Clase extendida\n";
parent::mostrarVar();
}
}
$extendida= newClaseExtendida();
$extendida->mostrarVar();
?>El resultado del ejemplo sería:
Clase extendida un valor predeterminado
When overriding a method, its signature must be compatible with the parent method. Otherwise, a fatal error is emitted, or, prior to PHP 8.0.0, anE_WARNINGlevel error is generated. A signature is compatible if it respects thevariancerules, makes a mandatory parameter optional, and if any new parameters are optional. This is known as the Liskov Substitution Principle, or LSP for short. Theconstructor, andprivatemethods are exempt from these signature compatibility rules, and thus won't emit a fatal error in case of a signature mismatch.
Ejemplo #10 Compatible child methods
<?php
classBase
{
public functionfoo(int $a) {
echo"Valid\n";
}
}
classExtend1extendsBase
{
functionfoo(int $a=5)
{
parent::foo($a);
}
}
classExtend2extendsBase
{
functionfoo(int $a,$b=5)
{
parent::foo($a);
}
}
$extended1= newExtend1();
$extended1->foo();
$extended2= newExtend2();
$extended2->foo(1);El resultado del ejemplo sería:
Valid Valid
The following examples demonstrate that a child method which removes a parameter, or makes an optional parameter mandatory, is not compatible with the parent method.
Ejemplo #11 Fatal error when a child method removes a parameter
<?php
classBase
{
public functionfoo(int $a=5) {
echo"Valid\n";
}
}
classExtendextendsBase
{
functionfoo()
{
parent::foo(1);
}
}Output of the above example in PHP 8 is similar to:
Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13
Ejemplo #12 Fatal error when a child method makes an optional parameter mandatory
<?php
classBase
{
public functionfoo(int $a=5) {
echo"Valid\n";
}
}
classExtendextendsBase
{
functionfoo(int $a)
{
parent::foo($a);
}
}Output of the above example in PHP 8 is similar to:
Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13
Renaming a method's parameter in a child class is not a signature incompatibility. However, this is discouraged as it will result in a runtimeErrorifnamed argumentsare used.
Ejemplo #13 Error when using named arguments and parameters were renamed in a child class
<?php
classA{
public functiontest($foo,$bar) {}
}
classBextendsA{
public functiontest($a,$b) {}
}
$obj= newB;
// Pass parameters according to A::test() contract
$obj->test(foo:"foo",bar:"bar");// ERROR!El resultado del ejemplo sería algo similar a:
Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
Stack trace:
#0 {main}
thrown in /in/XaaeN on line 14
La palabra reservadaclasses usada para la resolución de nombres de clases. Se puede obtener un string con el nombre completamente cualificado de la claseClassNameutilizandoClassName::class. Esto es particularmete útil con clases enespacios de nombres.
Ejemplo #14 Resolución de nombres de clases
<?php
namespaceNS{
classClassName{
}
echoClassName::class;
}
?>El resultado del ejemplo sería:
NS\ClassName
Nota:
La resolución de nombres de clases con
::classes una transformación durante la compilación. Esto significa que, en el instante de crear el string del nombre de la clase, aún no se ha realizado ninguna autocarga. Como consecuencia, los nombres de clases se expanden incluso si la clase no existe. No se emite ningún error en tal caso.Ejemplo #15 Missing class name resolution
<?php
printDoes\Not\Exist::class;
?>El resultado del ejemplo sería:
Does\Not\Exist
As of PHP 8.0.0, the::classconstant may also be used on objects. This resolution happens at runtime, not compile time. Its effect is the same as callingget_class()on the object.
Ejemplo #16 Object name resolution
<?php
namespaceNS{
classClassName{
}
}
$c= newClassName();
print$c::class;
?>El resultado del ejemplo sería:
NS\ClassName
As of PHP 8.0.0, properties and methods may also be accessed with the "nullsafe" operator instead:?->. The nullsafe operator works the same as property or method access as above, except that if the object being dereferenced isnullthennullwill be returned rather than an exception thrown. If the dereference is part of a chain, the rest of the chain is skipped.
The effect is similar to wrapping each access in anis_null()check first, but more compact.
Ejemplo #17 Nullsafe Operator
<?php
// As of PHP 8.0.0, this line:
$result=$repository?->getUser(5)?->name;
// Is equivalent to the following code block:
if (is_null($repository)) {
$result=null;
} else {
$user=$repository->getUser(5);
if (is_null($user)) {
$result=null;
} else {
$result=$user->name;
}
}
?>Nota:
The nullsafe operator is best used when null is considered a valid and expected possible value for a property or method return. For indicating an error, a thrown exception is preferable.
Las variables pertenecientes a una clase se llamanpropiedades. También se les puede llamar usando otros términos comoatributos, ocampos, pero para los propósitos de esta referencia se va a utilizarpropiedades. Éstas se definen usando una de las palabras reservadaspublic,protected, oprivate, opcionalmente, a partir de PHP 7.4, seguido de una declaración de tipo, seguida de una declaración de variable normal. Esta declaración puede incluir una inicialización, pero esta inicialización debe ser un valor deconstante.
Véase laVisibilidadpara más información sobre el significado depublic,protected, yprivate.
Nota:
Como alternativa y no recomendada de declarar las propiedades de una clase, ya que es para mantener la compatibilidad con PHP 4, se acepta el uso de la palabra reservada
var. Esta tratará la propiedad de forma idéntica a como se hubiera declarado comopublic.
Dentro de los métodos de una clase, se puede acceder a las propiedades no estáticas utilizando->(el operador de objeto):$this->propiedad(dondepropiedades el nombre de la propiedad). A las propiedades estáticas se puede acceder utilizando::(doble dos puntos):self::$propiedad. Véasela palabra reservada 'static'para más información sobre la diferencia entre propiedades estáticas y no estáticas.
La pseudovariable$thisestá disponible dentro de cualquier método de clase cuando éste es invocado dentro del contexto de un objeto.$thises una referencia al objeto invocador (usualmente el objeto al cual pertenece el método, aunque puede que sea otro objeto si el método es llamadoestáticamentedesde el contexto de un objeto secundario).
Ejemplo #1 Declaración de propiedades
<?php
classClaseSencilla
{
public$var1='hola '.'mundo';
public$var2= <<<EOD
hola mundo
EOD;
public$var3=1+2;
// Declaraciones de propiedades inválidas:
public$var4=self::miMetodoEstatico();
public$var5=$myVar;
// Declaraciones de propiedades válidas:
public$var6=miConstante;
public$var7= [true,false];
public$var8= <<<'EOD'
hola mundo
EOD;
}
?>Nota:
Existen varias funciones para manipular clases y objetos. VéaseLas funciones de clases/objetos.
A partir de PHP 7.4.0, las definiciones de propiedades pueden incluirseDeclaraciones de tipo, con la excepción de loscallable.
Ejemplo #2 Ejemplo de propiedades tipadas
<?php
classUser
{
publicint $id;
public ?string $name;
public function__construct(int $id, ?string $name)
{
$this->id=$id;
$this->name=$name;
}
}
$user= newUser(1234,null);
var_dump($user->id);
var_dump($user->name);
?>El resultado del ejemplo sería:
int(1234) NULL
Las propiedades tipadas deben ser inicializadas antes de acceder a ellas, de lo contrario se produce unError.
Ejemplo #3 Acceso a las propiedades
<?php
classShape
{
publicint $numberOfSides;
publicstring $name;
public functionsetNumberOfSides(int $numberOfSides):void
{
$this->numberOfSides=$numberOfSides;
}
public functionsetName(string $name):void
{
$this->name=$name;
}
public functiongetNumberOfSides():int
{
return$this->numberOfSides;
}
public functiongetName():string
{
return$this->name;
}
}
$triangle= newShape();
$triangle->setName("triangle");
$triangle->setNumberofSides(3);
var_dump($triangle->getName());
var_dump($triangle->getNumberOfSides());
$circle= newShape();
$circle->setName("circle");
var_dump($circle->getName());
var_dump($circle->getNumberOfSides());
?>El resultado del ejemplo sería:
string(8) "triangle" int(3) string(6) "circle" Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization
A partir de PHP 8.1.0, una propiedad se puede declarar con el modificadorreadonly(de solo lectura), lo que impide la modificación de la propiedad después de la inicialización.
Ejemplo #4 Ejemplo de propiedades de solo lectura
<?php
classTest{
publicreadonly string $prop;
public function__construct(string $prop) {
// Inicialización.
$this->prop=$prop;
}
}
$test= newTest("foobar");
// Lectura.
var_dump($test->prop);// string(6) "foobar"
// Reasignación ilegal. No importa que el valor asignado sea el mismo.
$test->prop="foobar";
// Error: Cannot modify readonly property Test::$prop
?>Nota:
El modificador readonly solo se puede aplicar a laspropiedades tipadas. Se puede crear una propiedad readonly sin restricciones mediante el tipomixed.
Nota:
El modificador readonly no son compatibles en propiedades estáticas.
Una propiedad readonly solo se puede inicializar una vez, y solo desde el ámbito en el que se ha declarado. Cualquier otra asignación o modificación de la propiedad dará lugar a una excepción deError.
Ejemplo #5 Inicialización ilegal de propiedades readonly
<?php
classTest1{
publicreadonly string $prop;
}
$test1= newTest1;
// Inicialización ilegal fuera del ámbito privado.
$test1->prop="foobar";
// Error: Cannot initialize readonly property Test1::$prop from global scope
?>Nota:
No se permite especificar un valor predeterminado explícito en las propiedades readonly, porque una propiedad readonly con un valor predeterminado es esencialmente la misma que una constante y, por lo tanto, no es particularmente útil.
<?php
classTest{
// Fatal error: Readonly property Test::$prop cannot have default value
publicreadonly int $prop=42;
}
?>
Nota:
Las propiedades readonly no pueden usarse con la funciónunset()una vez inicializadas. Sin embargo, es posible desactivar una propiedad readonly antes de la inicialización, desde el ámbito donde se ha declarado la propiedad.
Las modificaciones no son necesariamente asignaciones simples, todo lo siguiente también dará lugar a una excepciónError:
<?php
classTest{
public function__construct(
publicreadonly int $i=0,
publicreadonlyarray$ary= [],
) {}
}
$test= newTest;
$test->i+=1;
$test->i++;
++$test->i;
$test->ary[] =1;
$test->ary[0][] =1;
$ref=&$test->i;
$test->i=&$ref;
byRef($test->i);
foreach ($testas &$prop);
?>Sin embargo, las propiedades readonly no excluyen la mutabilidad interior. Los objetos (o recursos) almacenados en propiedades readonly aún pueden modificarse internamente:
<?php
classTest{
public function__construct(publicreadonly object $obj) {}
}
$test= newTest(newstdClass);
// Mutación interior.
$test->obj->foo=1;
// Reasignación ilegal.
$test->obj= newstdClass;
?>If trying to assign to a non existant property on anobject, PHP will automatically create a corresponding property. This dynamically created property willonlybe available on this class instance.
Es posible definir valores constantes en función de cada clase manteniéndola invariable. Las constantes se diferencian de las variables comunes en que no utilizan el símbolo$al declararlas o emplearlas. La visibilidad predeterminada de las constantes de clase espublic.
El valor debe ser una expresión constante, no (por ejemplo) una variable, una propiedad o una llamada a una función.
También es posible que las interfaces tenganconstantes. Consulte los ejemplos de ladocumentación de interfaces.
A partir de PHP 5.3.0, es posible referirse a una clase utilizando una variable. El valor de la variable no puede ser una palabra reservada (p.ej.,self,parentostatic).
Observe que las constantes de clase están asignadas una vez por clase, y no por cada instancia de la clase.
Ejemplo #1 Definición y uso de una constante
<?php
classMiClase
{
constCONSTANTE='valor constante';
functionmostrarConstante() {
echoself::CONSTANTE."\n";
}
}
echoMiClase::CONSTANTE."\n";
$nombreclase="MiClase";
echo$nombreclase::CONSTANTE."\n";// A partir de PHP 5.3.0
$clase= newMiClase();
$clase->mostrarConstante();
echo$clase::CONSTANTE."\n";// A partir de PHP 5.3.0
?>Ejemplo #2 Ejemplo de datos estáticos
<?php
classfoo{
// A partir de PHP 5.3.0
constBAR= <<<'EOT'
bar
EOT;
// A partir de PHP 5.3.0
constBAZ= <<<EOT
baz
EOT;
}
?>Nota:
El soporte para la inicialización de constantes con la sintaxis de Heredoc y Nowdoc fue agregado en PHP 5.3.0.
La constante especial::classestá disponible a partir de PHP 5.5.0, y permite la resolución de nombres de clase completamente cualificados en la compilación. Esto es útil para clases en espacios de nombres:
Ejemplo #3 Ejemplo de ::class en espacio de nombres
<?php
namespacefoo{
classbar{
}
echobar::class;// foo\bar
}
?>Ejemplo #4 Ejemplo de expresión constante
<?php
constUNO=1;
classfoo{
// A partir de PHP 5.6.0
constDOS=UNO*2;
constTRES=UNO+self::DOS;
constSENTENCIA='El valor de TRES es '.self::TRES;
}
?>Es posible proporcionar una expresión escalar que implique literales numéricos y de string y/o constantes en el contexto de una constante de clase.
Nota:
El soporte para expresiones constantes se añadió en PHP 5.6.0.
Ejemplo #5 Modificadores de visibilidad de constantes de clase
<?php
classFoo{
// A partir de PHP 7.1.0
public constBAR='bar';
private constBAZ='baz';
}
echoFoo::BAR,PHP_EOL;
echoFoo::BAZ,PHP_EOL;
?>Salida del ejemplo anterior en PHP 7.1:
bar Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …
Nota:
A partir de PHP 7.1.0, están permitidos los modificadores de visibilidad para constantes de clase.
Muchos desarrolladores que escriben aplicaciones orientadas a objetos crean un fichero fuente de PHP para cada definición de clase. Una de las mayores molestias es tener que hacer una larga lista de inclusiones al comienzo de cada script (uno por cada clase).
En PHP 5 esto ya no es necesario. La funciónspl_autoload_register()registra cualquier número de autocargadores, posibilitando que las clases e interfaces sean cargadas automáticamente si no están definidas actualmente. Al registrar autocargadores, a PHP se le da una última oportunidad de cargar las clases o interfaces antes de que falle por un error.
Aunque la función__autoload()también puede ser empleada para autocargar clases e interfaces, es preferible utilizar la funciónspl_autoload_register(). Esto es debido a que es una alternativa más flexible (posibilitando que se pueda especificar cualquier número de autocargadores en la aplicación, tales como los de las bibliotecas de terceros). Por esta razón, se desaconseja el uso de__autoload()y es obsoleto a partir de PHP 7.2.0.
Nota:
Antes de 5.3.0, las excepciones lanzadas en la función__autoload()no podían ser capturadas en el bloquecatch, resultando en un error fatal. Desde 5.3 en adelante, esto es posible simpre que, si se lanza una excepción personalizada, esté disponible la clase de la excepción personalizada. La función__autoload()podría utilizarse recursivamente para cargar la clase de excepción personalizada.
Nota:
La autocarga no está disponible si se utiliza PHP en elmodo interactivoCLI.
Nota:
Si el nombre de la clase se utiliza, por ejemplo, encall_user_func(), este puede contener algunos caracteres peligrosos tales como
../. Se recomienda no utilizar la entrada del usuario en tales funciones, o al menos verificar dicha entrada en__autoload().
Ejemplo #1 Ejemplo de autocarga
Este ejemplo intenta cargar las clasesMiClase1yMiClase2desde los ficherosMiClase1.phpyMiClase2.php, respectivamente.
<?php
spl_autoload_register(function ($nombre_clase) {
include$nombre_clase.'.php';
});
$obj= newMiClase1();
$obj2= newMiClase2();
?>Ejemplo #2 Otro ejemplo de autocarga
Este ejemplo intenta cargar la interfazIPrueba.
<?php
spl_autoload_register(function ($nombre) {
var_dump($nombre);
});
classFooimplementsIPrueba{
}
/*
string(7) "IPrueba"
Fatal error: Interface 'IPrueba' not found in ...
*/
?>Ejemplo #3 Autocarga con manejo de excepciones para 5.3.0+
Este ejemplo lanza una excepción y demuestra los bloques try/catch.
<?php
spl_autoload_register(function ($nombre) {
echo"Intentando cargar$nombre.\n";
throw newException("Imposible cargar$nombre.");
});
try {
$obj= newClaseNoCargable();
} catch (Exception $e) {
echo$e->getMessage(),"\n";
}
?>El resultado del ejemplo sería:
Intentando cargar ClaseNoCargable. Imposible cargar ClaseNoCargable.
Ejemplo #4 Autocarga con manejo de excepciones para 5.3.0+: Excepción personalizada ausente
Este ejemplo lanza una excepción para una excepción personalizada no cargable.
<?php
spl_autoload_register(function ($nombre) {
echo"Intentando cargar$nombre.\n";
throw newExcepciónAusente("Imposible cargar$nombre.");
});
try {
$obj= newClaseNoCargable();
} catch (Exception $e) {
echo$e->getMessage(),"\n";
}
?>El resultado del ejemplo sería:
Intentando cargar ClaseNoCargable. Intentando cargar ExcepciónAusente. Fatal error: Class 'ExcepciónAusente' not found in testExcepcionAusente.php on line 4
PHP permite a los desarrolladores declarar métodos constructores para las clases. Aquellas que tengan un método constructor lo invocarán en cada nuevo objeto creado, lo que lo hace idóneo para cualquier inicialización que el objeto pueda necesitar antes de ser usado.
Nota:Los constructores padres no son llamados implícitamente si la clase hija define un constructor. Para ejecutar un constructor padre, se requiere invocar aparent::__construct()desde el constructor hijo. Si el hijo no define un constructor, entonces se puede heredar de la clase madre como un método de clase normal (si no fue declarada como privada).
Ejemplo #1 Utilización de nuevos constructores unificados
<?php
classBaseClass{
function__construct() {
print"En el constructor BaseClass\n";
}
}
classSubClassextendsBaseClass{
function__construct() {
parent::__construct();
print"En el constructor SubClass\n";
}
}
classOtherSubClassextendsBaseClass{
// heredando el constructor BaseClass
}
// En el constructor BaseClass
$obj= newBaseClass();
// En el constructor BaseClass
// En el constructor SubClass
$obj= newSubClass();
// En el constructor BaseClass
$obj= newOtherSubClass();
?>A diferencia de otros métodos,__construct()is exempt from the usualsignature compatibility ruleswhen being extended.
Constructors are ordinary methods which are called during the instantiation of their corresponding object. As such, they may define an arbitrary number of arguments, which may be required, may have a type, and may have a default value. Constructor arguments are called by placing the arguments in parentheses after the class name.
Ejemplo #2 Using constructor arguments
<?php
classPoint{
protectedint $x;
protectedint $y;
public function__construct(int $x,int $y=0) {
$this->x=$x;
$this->y=$y;
}
}
// Pass both parameters.
$p1= newPoint(4,5);
// Pass only the required parameter. $y will take its default value of 0.
$p2= newPoint(4);
// With named parameters (as of PHP 8.0):
$p3= newPoint(y:5,x:4);
?>If a class has no constructor, or the constructor has no required arguments, the parentheses may be omitted.
Prior to PHP 8.0.0, classes in the global namespace will interpret a method named the same as the class as an old-style constructor. That syntax is deprecated, and will result in anE_DEPRECATEDerror but still call that function as a constructor. If both__construct()and a same-name method are defined,__construct()will be called.
In namespaced classes, or any class as of PHP 8.0.0, a method named the same as the class never has any special meaning.
Always use__construct()in new code.
As of PHP 8.0.0, constructor parameters may also be promoted to correspond to an object property. It is very common for constructor parameters to be assigned to a property in the constructor but otherwise not operated upon. Constructor promotion provides a short-hand for that use case. The example above could be rewritten as the following.
Ejemplo #3 Using constructor property promotion
<?php
classPoint{
public function__construct(protectedint $x, protectedint $y=0) {
}
}When a constructor argument includes a visibility modifier, PHP will interpret it as both an object property and a constructor argument, and assign the argument value to the property. The constructor body may then be empty or may contain other statements. Any additional statements will be executed after the argument values have been assigned to the corresponding properties.
Not all arguments need to be promoted. It is possible to mix and match promoted and not-promoted arguments, in any order. Promoted arguments have no impact on code calling the constructor.
Nota:
Object properties may not be typedcallabledue to engine ambiguity that would introduce. Promoted arguments, therefore, may not be typedcallableeither. Any othertype declarationis permitted, however.
Nota:
Attributes placed on a promoted constructor argument will be replicated to both the property and argument.
PHP only supports a single constructor per class. In some cases, however, it may be desirable to allow an object to be constructed in different ways with different inputs. The recommended way to do so is by using static methods as constructor wrappers.
Ejemplo #4 Using static creation methods
<?php
classProduct{
private ?int $id;
private ?string $name;
private function__construct(?int $id=null, ?string $name=null) {
$this->id=$id;
$this->name=$name;
}
public static functionfromBasicData(int $id,string $name): static {
$new= new static($id,$name);
return$new;
}
public static functionfromJson(string $json): static {
$data=json_decode($json);
return new static($data['id'],$data['name']);
}
public static functionfromXml(string $xml): static {
// Put your own logic here.
$data=convert_xml_to_array($xml);
$new= new static();
$new->id=$data['id'];
$new->name=$data['name'];
return$new;
}
}
$p1=Product::fromBasicData(5,'Widget');
$p2=Product::fromJson($some_json_string);
$p3=Product::fromXml($some_xml_string);The constructor may be made private or protected to prevent it from being called externally. If so, only a static method will be able to instantiate the class. Because they are in the same class definition they have access to private methods, even if not of the same object instance. The private constructor is optional and may or may not make sense depending on the use case.
The three public static methods then demonstrate different ways of instantiating the object.
fromBasicData()takes the exact parameters that are needed, then creates the object by calling the constructor and returning the result.fromJson()accepts a JSON string and does some pre-processing on it itself to convert it into the format desired by the constructor. It then returns the new object.fromXml()accepts an XML string, preprocesses it, and then creates a bare object. The constructor is still called, but as all of the parameters are optional the method skips them. It then assigns values to the object properties directly before returning the result.In all three cases, thestatickeyword is translated into the name of the class the code is in. In this case,Product.
PHP posee un concepto de destructor similar al de otros lenguajes orientados a objetos, tal como C++. El método destructor será llamado tan pronto como no hayan otras referencias a un objeto determinado, o en cualquier otra circunstancia de finalización.
Ejemplo #5 Ejemplo de Destructor
<?php
classMyDestructableClass
{
function__construct() {
print"En el constructor\n";
}
function__destruct() {
print"Destruyendo ".__CLASS__."\n";
}
}
$obj= newMyDestructableClass();Como los constructores, los destructores padre no serán llamados implícitamente por el motor. Para ejecutar un destructor padre, se deberá llamar explícitamente aparent::__destruct()en el interior del destructor. También como los constructores, una clase child puede heredar el destructor de los padres si no implementa uno propio.
El destructor será invocado aún si la ejecución del script es detenida usandoexit(). Llamar aexit()en un destructor evitará que se ejecuten las rutinas restantes de finalización.
Nota:
Los destructores invocados durante la finalización del script tienen los headers HTTP ya enviados. El directorio de trabajo en la fase de finalización del script puede ser diferente con algunos SAPIs (por ej., Apache).
Nota:
Intentar lanzar una excepción desde un destructor (invocado en la finalización del script) causa un error fatal.
La visibilidad de una propiedad, un método o (a partir de PHP 7.1.0) una constante se puede definir anteponiendo a su declaración una de las palabras reservadaspublic,protectedoprivate. A los miembros de clase declarados como 'public' se puede acceder desde donde sea; a los miembros declarados como 'protected', solo desde la misma clase, mediante clases heredadas o desde la clase padre. A los miembros declarados como 'private' únicamente se puede acceder desde la clase que los definió.
Las propiedades de clases deben ser definidas como 'public', 'private' o 'protected'. Si se declaran usandovar, serán definidas como 'public'.
Ejemplo #1 Declaración de propiedades
<?php
/**
* Definición de MyClass
*/
classMyClass
{
public$public='Public';
protected$protected='Protected';
private$private='Private';
functionprintHello()
{
echo$this->public;
echo$this->protected;
echo$this->private;
}
}
$obj= newMyClass();
echo$obj->public;// Funciona bien
echo$obj->protected;// Error Fatal
echo$obj->private;// Error Fatal
$obj->printHello();// Muestra Public, Protected y Private
/**
* Definición de MyClass2
*/
classMyClass2extendsMyClass
{
// Se pueden redeclarar las propiedades pública y protegida, pero no la privada
public$public='Public2';
protected$protected='Protected2';
functionprintHello()
{
echo$this->public;
echo$this->protected;
echo$this->private;
}
}
$obj2= newMyClass2();
echo$obj2->public;// Funciona bien
echo$obj2->protected;// Error Fatal
echo$obj2->private;// Undefined
$obj2->printHello();// Muestra Public2, Protected2, Undefined
?>Nota:La forma de declaración de una variable de PHP 4 con la palabra clavevartodavía es soportado (como un sinónimo de public) por razones de compatibilidad. En PHP 5 antes de 5.1.3, su uso genera un Warning
E_STRICT.
Los métodos de clases pueden ser definidos como public, private, o protected. Aquellos declarados sin ninguna palabra clave de visibilidad explícita serán definidos como public.
Ejemplo #2 Declaración de métodos
<?php
/**
* Definición de MyClass
*/
classMyClass
{
// Declaración de un constructor public
public function__construct() { }
// Declaración de un método public
public functionMyPublic() { }
// Declaración de un método protected
protected functionMyProtected() { }
// Declaración de un método private
private functionMyPrivate() { }
// Esto es public
functionFoo()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate();
}
}
$myclass= newMyClass;
$myclass->MyPublic();// Funciona
$myclass->MyProtected();// Error Fatal
$myclass->MyPrivate();// Error Fatal
$myclass->Foo();// Public, Protected y Private funcionan
/**
* Definición de MyClass2
*/
classMyClass2extendsMyClass
{
// Esto es public
functionFoo2()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate();// Error Fatal
}
}
$myclass2= newMyClass2;
$myclass2->MyPublic();// Funciona
$myclass2->Foo2();// Public y Protected funcionan, pero Private no
classBar
{
public functiontest() {
$this->testPrivate();
$this->testPublic();
}
public functiontestPublic() {
echo"Bar::testPublic\n";
}
private functiontestPrivate() {
echo"Bar::testPrivate\n";
}
}
classFooextendsBar
{
public functiontestPublic() {
echo"Foo::testPublic\n";
}
private functiontestPrivate() {
echo"Foo::testPrivate\n";
}
}
$myFoo= newFoo();
$myFoo->test();// Bar::testPrivate
// Foo::testPublic
?>A partir de PHP 7.1.0, las constantes de clase se pueden definir como públicas, privadas o protegidas. Las constantes declaradas sin una visibilidad explítica serán definidas como públicas.
Ejemplo #3 Declaración de constantes a partir de PHP 7.1.0
<?php
/**
* Definir MiClase
*/
classMiClase
{
// Declarar una constante pública
public constMY_PUBLIC='public';
// Declarar una constante protegida
protected constMY_PROTECTED='protected';
// Declarar una constante privada
private constMY_PRIVATE='private';
public functionfoo()
{
echoself::MY_PUBLIC;
echoself::MY_PROTECTED;
echoself::MY_PRIVATE;
}
}
$myclass= newMiClase();
MiClase::MY_PUBLIC;// Funciona
MiClase::MY_PROTECTED;// Error fatal
MiClase::MY_PRIVATE;// Error fatal
$myclass->foo();// Funcionan Public, Protected y Private
/**
* Definir MiClase2
*/
classMiClase2extendsMiClase
{
// Esta es pública
functionfoo2()
{
echoself::MY_PUBLIC;
echoself::MY_PROTECTED;
echoself::MY_PRIVATE;// Error fatal
}
}
$myclass2= newMiClase2;
echoMiClase2::MY_PUBLIC;// Funciona
$myclass2->foo2();// Funcionan Public y Protected, pero no Private
?>Los objetos del mismo tipo tendrán acceso a los miembros private y protected entre ellos aunque no sean de la misma instancia. Esto es porque los detalles específicos de implementación ya se conocen cuando se encuentra dentro de estos objetos.
Ejemplo #4 Accediendo a miembros private del mismo tipo de objeto
<?php
classTest
{
private$foo;
public function__construct($foo)
{
$this->foo=$foo;
}
private functionbar()
{
echo'Método private accedido.';
}
public functionbaz(Test $other)
{
// Se puede cambiar la propiedad private:
$other->foo='hola';
var_dump($other->foo);
// También se puede invocar al método private:
$other->bar();
}
}
$test= newTest('test');
$test->baz(newTest('other'));
?>El resultado del ejemplo sería:
string(5) "hola" Método private accedido.
La herencia es un principio de programación bien establecido y PHP hace uso de él en su modelado de objetos. Este principio afectará la manera en que muchas clases y objetos se relacionan unas con otras.
Por ejemplo, cuando se extiende una clase, la subclase hereda todos los métodos públicos y protegidos de la clase padre. A menos que una clase sobrescriba esos métodos, mantendrán su funcionalidad original.
Esto es útil para la definición y abstracción de la funcionalidad y permite la implementación de funcionalidad adicional en objetos similares sin la necesidad de reimplementar toda la funcionalidad compartida.
Los métodos privados de una clase padre no son accesibles para una clase hija. Como resultado, las clases hijas pueden reimplementar un método privado sin tener en cuenta las reglas de herencia normales. Antes de PHP 8.0.0, sin embargo, se aplicaban las restriccionesfinalystatica los métodos privados. A partir de PHP 8.0.0, la única restricción de métodos privados esprivate finalque se aplica en el constructor de la clase, ya que es una forma común de "deshabilitar" el constructor cuando es usado en métodos estáticos de fábrica (Patrón Factory).
Lavisibilidadde los métodos, propiedades y constantes pueden ser relajarse, por ejemplo, un méetodoprotectedpuede marcase comopublic, pero no pueden restringirse, por ejemplo. marcando una propiedadpubliccomoprivate.
Nota:
A menos que la carga automática sea utilizada, entonces las clases deben ser definidas antes de ser usadas. Si una clase se extiende a otra, entonces la clase padre debe ser declarada antes de la estructura de clase hija. Esta regla se aplica a las clases que heredan de otras clases e interfaces.
Nota:
No está permitido sobrescribir una propiedad de lectura-escritura con unapropiedad de sólo lecturao viceversa.
<?php
classA{
publicint $prop;
}
classBextendsA{
// Ilegal: lectura-escritura -> sólo lectura
publicreadonly int $prop;
}
?>
Ejemplo #1 Ejemplo de herencia
<?php
classFoo
{
public functionprintItem($string)
{
echo'Foo: '.$string.PHP_EOL;
}
public functionprintPHP()
{
echo'PHP is great.'.PHP_EOL;
}
}
classbarextendsFoo
{
public functionprintItem($string)
{
echo'Bar: '.$string.PHP_EOL;
}
}
$foo= newFoo();
$bar= newBar();
$foo->printItem('baz');// Salida: 'Foo: baz'
$foo->printPHP();// Salida: 'PHP is great'
$bar->printItem('baz');// Salida: 'Bar: baz'
$bar->printPHP();// Salida: 'PHP is great'
?>Prior to PHP 8.1, most internal classes or methods didn't declare their return types, and any return type was allowed when extending them.
As of PHP 8.1.0, most internal methods started to "tentatively" declare their return type, in that case the return type of methods should be compatible with the parent being extended; otherwise, a deprecation notice is emitted. Note that lack of an explicit return declaration is also considered a signature mismatch, and thus results in the deprecation notice.
If the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a#[ReturnTypeWillChange]attribute can be added to silence the deprecation notice.
Ejemplo #2 The overriding method does not declare any return type
<?php
classMyDateTimeextendsDateTime
{
public functionmodify(string $modifier) { returnfalse; }
}
// "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
?>Ejemplo #3 The overriding method declares a wrong return type
<?php
classMyDateTimeextendsDateTime
{
public functionmodify(string $modifier): ?DateTime{ returnnull; }
}
// "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
?>Ejemplo #4 The overriding method declares a wrong return type without a deprecation notice
<?php
classMyDateTimeextendsDateTime
{
/**
* @return DateTime|false
*/
#[ReturnTypeWillChange]
public functionmodify(string $modifier) { returnfalse; }
}
// No notice is triggered
?>El Operador de Resolución de Ámbito (también denominado Paamayim Nekudotayim) o en términos simples, el doble dos-puntos, es un token que permite acceder a elementosestáticos,constantes, y sobrescribir propiedades o métodos de una clase.
Cuando se hace referencia a estos items desde el exterior de la definición de la clase, se utiliza el nombre de la clase.
A partir de PHP 5.3.0, es posible hacer referencia a una clase usando una variable. El valor de la variable no puede ser una palabra clave (por ej.,self,parentystatic).
Paamayim Nekudotayim podría, en un principio, parecer una extraña elección para bautizar a un doble dos-puntos. Sin embargo, mientras se escribía el Zend Engine 0.5 (que utilizó PHP 3), asi es como el equipo Zend decidió bautizarlo. En realidad, significa doble dos-puntos - en Hebreo!
Ejemplo #1 :: desde el exterior de la definición de la clase
<?php
classMyClass{
constCONST_VALUE='Un valor constante';
}
$classname='MyClass';
echo$classname::CONST_VALUE;// A partir de PHP 5.3.0
echoMyClass::CONST_VALUE;
?>Las tres palabras claves especialesself,parentystaticson utilizadas para acceder a propiedades y métodos desde el interior de la definición de la clase.
Ejemplo #2 :: desde el interior de la definición de la clase
<?php
classOtherClassextendsMyClass
{
public static$my_static='variable estática';
public static functiondoubleColon() {
echoparent::CONST_VALUE."\n";
echoself::$my_static."\n";
}
}
$classname='OtherClass';
$classname::doubleColon();// A partir de PHP 5.3.0
OtherClass::doubleColon();
?>Cuando una clase extendida sobrescribe la definición parent de un método, PHP no invocará al método parent. Depende de la clase extendida el hecho de llamar o no al método parent. Esto también se aplica a definiciones de métodosConstructores y Destructores,Sobrecarga, yMágicos.
Ejemplo #3 Invocando a un método parent
<?php
classMyClass
{
protected functionmyFunc() {
echo"MyClass::myFunc()\n";
}
}
classOtherClassextendsMyClass
{
// Sobrescritura de definición parent
public functionmyFunc()
{
// Pero todavía se puede llamar a la función parent
parent::myFunc();
echo"OtherClass::myFunc()\n";
}
}
$class= newOtherClass();
$class->myFunc();
?>Véase tambiénalgunos ejemplos de trucos de llamadas estáticas.
Esta página describe el uso de la palabra reservadastaticpara definir métodos y propiedades estáticos.statictambién se puede usar paradefinir variables estáticasy paraenlaces estáticos en tiempo de ejecución. Por favor, consulte estas páginas para más información sobre estos significados destatic.
Declarar propiedades o métodos de clases como estáticos los hacen accesibles sin la necesidad de instanciar la clase. Una propiedad declarada como static no puede ser accedida con un objeto de clase instanciado (aunque un método estático sí lo puede hacer).
Por motivos de compatibilidad con PHP 4, si no se utiliza ninguna declaración devisibilidad, se tratará a las propiedades o métodos como si hubiesen sido definidos comopublic.
Debido a que los métodos estáticos se pueden invocar sin tener creada una instancia del objeto, la seudovariable$thisno está disponible dentro de los métodos declarados como estáticos.
En PHP 5, llamar a métodos no estáticos de forma estática genera una advertencia de nivelE_STRICT.
En PHP 7, llamar a métodos no estáticos de forma estática está obsoleto y generará una advertenciaE_DEPRECATED. El soporte para las llamadas a métodos no estáticos de forma estática podría ser eliminado en el futuro.
Ejemplo #1 Ejemplo de método estático
<?php
classFoo{
public static functionunMetodoEstatico() {
// ...
}
}
Foo::unMetodoEstatico();
$nombre_clase='Foo';
$nombre_clase::unMetodoEstatico();// A partir de PHP 5.3.0
?>No se puede acceder a las propiedades estáticas a través del objeto utilizando el operador flecha (->).
Como cualquier otra variable estática de PHP, las propiedades estáticas sólo pueden ser inicializadas utilizando un string literal o una constante; las expresiones no están permitidas. Por tanto, se puede inicializar una propiedad estática con enteros o arrays (por ejemplo), pero no se puede hacer con otra variable, con el valor de devolución de una función, o con un objeto.
A partir de PHP 5.3.0, es posible hacer referencia a una clase usando una variable. El valor de la variable no puede ser una palabra reservada (p.ej.,self,parentystatic).
Ejemplo #2 Ejemplo de propiedad estática
<?php
classFoo
{
public static$mi_static='foo';
public functionvalorStatic() {
returnself::$mi_static;
}
}
classBarextendsFoo
{
public functionfooStatic() {
returnparent::$mi_static;
}
}
printFoo::$mi_static."\n";
$foo= newFoo();
print$foo->valorStatic() ."\n";
print$foo->mi_static."\n";// "Propiedad" mi_static no definida
print$foo::$mi_static."\n";
$nombreClase='Foo';
print$nombreClase::$mi_static."\n";// A partir de PHP 5.3.0
printBar::$mi_static."\n";
$bar= newBar();
print$bar->fooStatic() ."\n";
?>PHP 5 introduce clases y métodos abstractos. Las clases definidas como abstractas no se pueden instanciar y cualquier clase que contiene al menos un método abstracto debe ser definida como tal. Los métodos definidos como abstractos simplemente declaran la firma del método, pero no pueden definir la implementación.
Cuando se hereda de una clase abstracta, todos los métodos definidos como abstractos en la declaración de la clase madre deben ser definidos en la clase hija; además, estos métodos deben ser definidos con la misma (o con una menos restrictiva)visibilidad. Por ejemplo, si el método abstracto está definido como protegido, la implementación de la función debe ser definida como protegida o pública, pero nunca como privada. Por otra parte, las firmas de los métodos tienen que coincidir, es decir, la declaración de tipos y el número de argumentos requeridos deben ser los mismos. Por ejemplo, si la clase derivada define un argumento opcional y la firma del método abstracto no lo hace, no habría conflicto con la firma. Esto también se aplica a los constructores a partir de PHP 5.4. Antes de PHP 5.4, las firmas del constructor podían ser diferentes.
Ejemplo #1 Ejemplo de clase abstracta
<?php
abstract classClaseAbstracta
{
// Forzar la extensión de clase para definir este método
abstract protected functiongetValor();
abstract protected functionvalorPrefijo($prefijo);
// Método común
public functionimprimir() {
print$this->getValor() ."\n";
}
}
classClaseConcreta1extendsClaseAbstracta
{
protected functiongetValor() {
return"ClaseConcreta1";
}
public functionvalorPrefijo($prefijo) {
return"{$prefijo}ClaseConcreta1";
}
}
classClaseConcreta2extendsClaseAbstracta
{
public functiongetValor() {
return"ClaseConcreta2";
}
public functionvalorPrefijo($prefijo) {
return"{$prefijo}ClaseConcreta2";
}
}
$clase1= newClaseConcreta1;
$clase1->imprimir();
echo$clase1->valorPrefijo('FOO_') ."\n";
$clase2= newClaseConcreta2;
$clase2->imprimir();
echo$clase2->valorPrefijo('FOO_') ."\n";
?>El resultado del ejemplo sería:
ClaseConcreta1 FOO_ClaseConcreta1 ClaseConcreta2 FOO_ClaseConcreta2
Ejemplo #2 Ejemplo de clase abstracta
<?php
abstract classClaseAbstracta
{
// El método abstracto sólo necesita definir los argumentos requeridos
abstract protected functionnombrePrefijo($nombre);
}
classClaseConcretaextendsClaseAbstracta
{
// La clase derivada puede definir parámetros opcionales que no estén en la estructura del prototipo
public functionnombrePrefijo($nombre,$separador=".") {
if ($nombre=="Pacman") {
$prefijo="Mr";
} elseif ($nombre=="Pacwoman") {
$prefijo="Mrs";
} else {
$prefijo="";
}
return"{$prefijo}{$separador}{$nombre}";
}
}
$clase= newClaseConcreta;
echo$clase->nombrePrefijo("Pacman"),"\n";
echo$clase->nombrePrefijo("Pacwoman"),"\n";
?>El resultado del ejemplo sería:
Mr. Pacman Mrs. Pacwoman
El código antiguo que no tenga clases o funciones definidas por el usuario llamadas 'abstract' deberían ejecutarse sin modificaciones.
Las interfaces de objetos permiten crear código con el cual especificar qué métodos deben ser implementados por una clase, sin tener que definir cómo estos métodos son manipulados.
Las interfaces se definen de la misma manera que una clase, aunque reemplazando la palabra reservadaclasspor la palabra reservadainterfacey sin que ninguno de sus métodos tenga su contenido definido.
Todos los métodos declarados en una interfaz deben ser públicos, ya que ésta es la naturaleza de una interfaz.
implementsPara implementar una interfaz, se utiliza el operadorimplements. Todos los métodos en una interfaz deben ser implementados dentro de la clase; el no cumplir con esta regla resultará en un error fatal. Las clases pueden implementar más de una interfaz si se deseara, separándolas cada una por una coma.
Nota:
Antes de PHP 5.3.9, una clase no puede implementar dos interfaces que especifiquen un método con el mismo nombre, ya que podría causar ambigüedad. Las versiones más recientes de PHP permiten esto siempre y cuando los métodos duplicados tengan la misma firma.
Nota:
Las interfaces se pueden extender al igual que las clases utilizando el operadorextends.
Nota:
La clase que implemente una interfaz debe utilizar exactamente las mismas estructuras de métodos que fueron definidos en la interfaz. De no cumplir con esta regla, se generará un error fatal.
ConstantesEs posible tener constantes dentro de las interfaces. Las constantes de interfaces funcionan como lasconstantes de clasesexcepto porque no pueden ser sobrescritas por una clase/interfaz que las herede.
Ejemplo #1 Ejemplo de interfaz
<?php
// Declarar la interfaz 'iTemplate'
interfaceiTemplate
{
public functionsetVariable($name,$var);
public functiongetHtml($template);
}
// Implementar la interfaz
// Ésto funcionará
classTemplateimplementsiTemplate
{
private$vars= array();
public functionsetVariable($name,$var)
{
$this->vars[$name] =$var;
}
public functiongetHtml($template)
{
foreach($this->varsas$name=>$value) {
$template=str_replace('{'.$name.'}',$value,$template);
}
return$template;
}
}
// Ésto no funcionará
// Error fatal: La Clase BadTemplate contiene un método abstracto
// y por lo tanto debe declararse como abstracta (iTemplate::getHtml)
classBadTemplateimplementsiTemplate
{
private$vars= array();
public functionsetVariable($name,$var)
{
$this->vars[$name] =$var;
}
}
?>Ejemplo #2 Interfaces extensibles
<?php
interfacea
{
public functionfoo();
}
interfacebextendsa
{
public functionbaz(Baz $baz);
}
// Ésto sí funcionará
classcimplementsb
{
public functionfoo()
{
}
public functionbaz(Baz $baz)
{
}
}
// Ésto no funcionará y resultará en un error fatal
classdimplementsb
{
public functionfoo()
{
}
public functionbaz(Foo $foo)
{
}
}
?>Ejemplo #3 Herencia múltiple de interfaces
<?php
interfacea
{
public functionfoo();
}
interfaceb
{
public functionbar();
}
interfacecextendsa,b
{
public functionbaz();
}
classdimplementsc
{
public functionfoo()
{
}
public functionbar()
{
}
public functionbaz()
{
}
}
?>Ejemplo #4 Interfaces con constantes
<?php
interfacea
{
constb='Interface constant';
}
// Imprime: Interface constant
echoa::b;
// Sin embargo ésto no funcionará ya que no está permitido
// sobrescribir constantes
classbimplementsa
{
constb='Class constant';
}
?>Una interfaz, junto con la determinación de tipos, proveen una buena forma de asegurarse que determinado objeto contiene métodos particulares. Vea el operadorinstanceofy ladeclaración de tipos.
Desde su versión 5.4.0, PHP implementa una metodología de reutilización de código llamada Traits.
Los rasgos («traits» en inglés) son un mecanismo de reutilización de código en lenguajes de herencia simple, como PHP. El objetivo de un rasgo es el de reducir las limitaciones propias de la herencia simple permitiendo que los desarrolladores reutilicen a voluntad conjuntos de métodos sobre varias clases independientes y pertenecientes a clases jerárquicas distintas. La semántica a la hora combinar Traits y clases se define de tal manera que reduzca su complejidad y se eviten los problemas típicos asociados a la herencia múltiple y a los Mixins.
Un Trait es similar a una clase, pero con el único objetivo de agrupar funcionalidades muy específicas y de una manera coherente. No se puede instanciar directamente un Trait. Es por tanto un añadido a la herencia tradicional, y habilita la composición horizontal de comportamientos; es decir, permite combinar miembros de clases sin tener que usar herencia.
Ejemplo #1 Ejemplo de rasgo
<?php
traitezcReflectionReturnInfo{
functiongetReturnType() {/*1*/}
functiongetReturnDescription() {/*2*/}
}
classezcReflectionMethodextendsReflectionMethod{
useezcReflectionReturnInfo;
/* ... */
}
classezcReflectionFunctionextendsReflectionFunction{
useezcReflectionReturnInfo;
/* ... */
}
?>Los miembros heredados de una clase base se sobrescriben cuando se inserta otro miembro homónimo desde un Trait. De acuerdo con el orden de precedencia, los miembros de la clase actual sobrescriben los métodos del Trait, que a su vez sobrescribe los métodos heredados.
Ejemplo #2 Ejemplo de Orden de Precedencia
Se sobrescribe un miembro de la clase base con el método insertado en MiHolaMundo a partir del Trait DecirMundo. El comportamiento es el mismo para los métodos definidos en la clase MiHolaMundo. Según el orden de precedencia los métodos de la clase actual sobrescriben los métodos del Trait, a la vez que el Trait sobrescribe los métodos de la clase base.
<?php
classBase{
public functiondecirHola() {
echo'¡Hola ';
}
}
traitDecirMundo{
public functiondecirHola() {
parent::decirHola();
echo'Mundo!';
}
}
classMiHolaMundoextendsBase{
useDecirMundo;
}
$o= newMiHolaMundo();
$o->decirHola();
?>El resultado del ejemplo sería:
¡Hola Mundo!
Ejemplo #3 Ejemplo de Orden de Precedencia #2
<?php
traitHolaMundo{
public functiondecirHola() {
echo'¡Hola Mundo!';
}
}
classElMundoNoEsSuficiente{
useHolaMundo;
public functiondecirHola() {
echo'¡Hola Universo!';
}
}
$o= newElMundoNoEsSuficiente();
$o->decirHola();
?>El resultado del ejemplo sería:
¡Hola Universo!
Se pueden insertar múltiples Traits en una clase, mediante una lista separada por comas en la sentencia use.
Ejemplo #4 Uso de varios rasgos
<?php
traitHola{
public functiondecirHola() {
echo'Hola ';
}
}
traitMundo{
public functiondecirMundo() {
echo'Mundo';
}
}
classMiHolaMundo{
useHola,Mundo;
public functiondecirAdmiración() {
echo'!';
}
}
$o= newMiHolaMundo();
$o->decirHola();
$o->decirMundo();
$o->decirAdmiración();
?>El resultado del ejemplo sería:
Hola Mundo!
Si dos Traits insertan un método con el mismo nombre, se produce un error fatal, siempre y cuando no se haya resuelto explicitamente el conflicto.
Para resolver los conflictos de nombres entre Traits en una misma clase, se debe usar el operadorinsteadofpara elegir unívocamente uno de los métodos conflictivos.
Como esto solamente permite excluir métodos, se puede utilizar el operadoraspara añadir un alias a uno de los métodos. Observe que el operadorasno renombra el método ni afecta a cualquier otro método.
Ejemplo #5 Resolución de Conflictos
En este ejemplo, Talker utiliza los traits A y B. Como A y B tienen métodos conflictos, se define el uso de la variante de smallTalk del trait B, y la variante de bigTalk del trait A.
Aliased_Talker hace uso del operadoraspara poder usar la implementación de bigTalk de B, bajo el alias adicionaltalk.
<?php
traitA{
public functionsmallTalk() {
echo'a';
}
public functionbigTalk() {
echo'A';
}
}
traitB{
public functionsmallTalk() {
echo'b';
}
public functionbigTalk() {
echo'B';
}
}
classTalker{
useA,B{
B::smallTalkinsteadofA;
A::bigTalkinsteadofB;
}
}
classAliased_Talker{
useA,B{
B::smallTalkinsteadofA;
A::bigTalkinsteadofB;
B::bigTalkastalk;
}
}
?>Nota:
Antes de PHP 7.0, definir una propiedad en una clase con el mismo nombre que en un rasgo lanzaba un
E_STRICTsi la definición de la clase era compatible (misma visivilidad y mismo valor inicial).
Al usar el operadoras, se puede también ajustar la visibilidad del método en la clase exhibida.
Ejemplo #6 Modificar la Visibilidad de un Método
<?php
traitHolaMundo{
public functiondecirHola() {
echo'Hola Mundo!';
}
}
// Cambiamos visibilidad de decirHola
classMiClase1{
useHolaMundo{decirHolaas protected; }
}
// Método alias con visibilidad cambiada
// La visibilidad de decirHola no cambia
classMiClase2{
useHolaMundo{decirHolaas privatemiPrivadoHola; }
}
?>Al igual que las clases, los Traits también pueden hacer uso de otros Traits. Al usar uno o más traits en la definición de un trait, éste puede componerse parcial o completamente de miembros definidos en esos otros traits.
Ejemplo #7 Traits compuestos de traits
<?php
traitHola{
public functiondecirHola() {
echo'Hola ';
}
}
traitMundo{
public functiondecirMundo() {
echo'Mundo!';
}
}
traitHolaMundo{
useHola,Mundo;
}
classMiHolaMundo{
useHolaMundo;
}
$o= newMiHolaMundo();
$o->decirHola();
$o->decirMundo();
?>El resultado del ejemplo sería:
Hola Mundo!
Los traits soportan el uso de métodos abstractos para imponer requisitos a la clase a la que se exhiban.
Una clase concreta cumple este requisito definiendo un método concreto con el mismo nombre; su firma puede ser diferente.
Ejemplo #8 Expresar Resquisitos con Métodos Abstractos
<?php
traitHola{
public functiondecirHolaMundo() {
echo'Hola'.$this->obtenerMundo();
}
abstract public functionobtenerMundo();
}
classMiHolaMundo{
private$mundo;
useHola;
public functionobtenerMundo() {
return$this->mundo;
}
public functionasignarMundo($val) {
$this->mundo=$val;
}
}
?>Los trait pueden definir miembros y métodos estáticos.
Ejemplo #9 Variables estáticas
<?php
traitContador{
public functioninc() {
static$c=0;
$c=$c+1;
echo"$c\n";
}
}
classC1{
useContador;
}
classC2{
useContador;
}
$o= newC1();$o->inc();// echo 1
$p= newC2();$p->inc();// echo 1
?>Ejemplo #10 Métodos Estáticos
<?php
traitEjemploEstatico{
public static functionhacerAlgo() {
return'Hacer algo';
}
}
classEjemplo{
useEjemploEstatico;
}
Ejemplo::hacerAlgo();
?>Los traits también pueden definir propiedades.
Ejemplo #11 Definir Propiedades
<?php
traitPropiedadesTrait{
public$x=1;
}
classEjemploPropiedades{
usePropiedadesTrait;
}
$ejemplo= newEjemploPropiedades;
$ejemplo->x;
?>Si un trait define una propiedad, una clase no puede definir una propiedad con el mismo nombre, a menos que sea compatible (misma visibilidad y mismo valor inicial), si no, se emitirá un error fatal. Antes de PHP 7.0, definir una propiedad en una clase con la misma visibilidad y el mismo valor inicial que en el rasgo, emitía un aviso E_STRICT.
Ejemplo #12 Resolución de Conflictos
<?php
traitPropiedadesTrait{
public$misma=true;
public$diferente=false;
}
classEjemploPropiedades{
usePropiedadesTrait;
public$misma=true;// Permitido a partir de PHP 7.0.0; aviso E_STRICT anteriormente
public$diferente=true;// Error fatal
}
?>En PHP 7 se ha añadido soporte para clases anónimas. Las clases anónimas son útiles cuando es necesario crear objetos sencillos y únicos.
<?php
// Código anterior a PHP 7
classLogger
{
public functionlog($msg)
{
echo$msg;
}
}
$util->setLogger(newLogger());
// Código de PHP 7+
$util->setLogger(new class {
public functionlog($msg)
{
echo$msg;
}
});Pueden pasar argumentos a través de sus constructores, extender otras clases, implementar interfaces, y utilizar rasgos al igual que una clase normal:
<?php
classSomeClass{}
interfaceSomeInterface{}
traitSomeTrait{}
var_dump(new class(10) extendsSomeClassimplementsSomeInterface{
private$num;
public function__construct($num)
{
$this->num=$num;
}
useSomeTrait;
});El resultado del ejemplo sería:
object(class@anonymous)#1 (1) {
["Command line code0x104c5b612":"class@anonymous":private]=>
int(10)
}
El anidamiento de una clase anónima dentro de otra clase no le proporciona acceso a ningún método o propiedad privados o protegidos de la clase externa. Para utilizar las propiedades o métodos protegidos de la clase externa, la clase anónima puede extender la clase externa. Para utilizar las propiedades privadas de la clase externa en la clase anónima, estos deben pasarse a su constructor:
<?php
classExterna
{
private$prop=1;
protected$prop2=2;
protected functionfunc1()
{
return3;
}
public functionfunc2()
{
return new class($this->prop) extendsExterna{
private$prop3;
public function__construct($prop)
{
$this->prop3=$prop;
}
public functionfunc3()
{
return$this->prop2+$this->prop3+$this->func1();
}
};
}
}
echo (newExterna)->func2()->func3();El resultado del ejemplo sería:
6
Todos los objetos creados por la misma declaración de clase anónima son instancias de esa misma clase.
<?php
functionclase_anónima()
{
return new class {};
}
if (get_class(clase_anónima()) ===get_class(clase_anónima())) {
echo'misma clase';
} else {
echo'clase diferente';
}El resultado del ejemplo sería:
misma clase
Nota:
Observe que el motor le asigna un nombre a las clases anónimas, como se demuestra en el siguiente ejemplo. Este nombre name ha de considerarse un detalle de implementación del cual no se debería depender.
<?php
echoget_class(new class {});El resultado del ejemplo sería algo similar a:
class@anonymous/in/oNi1A0x7f8636ad2021
La sobrecarga en PHP ofrece los medios paracrear
dinámicamente propiedades y métodos. Estas entidades dinámicas se procesan por los métodos mágicos que se pueden establecer en una clase para diversas acciones.
Se invoca a los métodos de sobrecarga cuando se interactúa con propiedades o métodos que no se han declarado o que no sonvisiblesen el ámbito activo. A lo largo de esta sección usaremos los términospropiedades inaccesibles
ymétodos inaccesibles
para referirnos a esta combinación de declaración y visibilidad.
Todos los métodos sobrecargados deben definirse comopublic.
Nota:
No se puede pasar ninguno de los parámetros de estos métodos mágicospor referencia.
Nota:
La interpretación de PHP de
overloadinges distinta de la mayoría de los lenguajes orientados a objetos. La sobrecarga tradicionalmente ofrece la capacidad de tener múltiples métodos con el mismo nombre, pero con un tipo o un número distinto de parámetros.
| Versión | Descripción |
|---|---|
| 5.3.0 | Se añadió__callStatic. Se añadieron advertencias para hacer cumplir la visibilidad pública e impedir la declaración static. |
| 5.1.0 | Se añadieron__isset()y__unset(). Se añadió el soporte para__get()para la sobrecarga de propiedades privadas. |
| 5.0.0 | Se añadió__get(). |
$name):bool$name):void__set()se ejecuta al escribir datos sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.
__get()se utiliza para consultar datos a partir de propiedades inaccesibles (protegidas o privadas) o inexistentes.
__isset()se lanza al llamar aisset()o aempty()sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.
__unset()se invoca cuando se usaunset()sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.
El parámetro$namees el nombre de la propiedad con la que se está interactuando. En el método__set()el parámetro$valueespecifica el valor que se debe asignar a la propiedad$name.
La sobrecarga de propiedades sólo funciona en contextos de objetos. Estos métodos mágicos no se lanzarán en contextos estáticos. Por esa razón, no se deben declarar comoestáticos. Desde PHP 5.3.0, se emite un aviso si alguno de los métodos de sobrecarga es declarado comostatic.
Nota:
Debido a la forma en que PHP procesa el operador de asignación, el valor que devuelve__set()se ignora. Del mismo modo, nunca se llama a__get()al encadenar asignaciones como esta:
$a = $obj->b = 8;
Ejemplo #1 Sobrecarga de propiedades mediante los métodos__get(),__set(),__isset()y__unset()
<?php
classPropertyTest
{
/** Localización de los datos sobrecargados. */
private$data= array();
/** La sobrecarga no se usa en propiedades declaradas. */
public$declared=1;
/** La sobre carga sólo funciona aquí al acceder desde fuera de la clase. */
private$hidden=2;
public function__set($name,$value)
{
echo"Estableciendo '$name' a '$value'\n";
$this->data[$name] =$value;
}
public function__get($name)
{
echo"Consultando '$name'\n";
if (array_key_exists($name,$this->data)) {
return$this->data[$name];
}
$trace=debug_backtrace();
trigger_error(
'Propiedad indefinida mediante __get(): '.$name.
' en '.$trace[0]['file'] .
' en la línea '.$trace[0]['line'],
E_USER_NOTICE);
returnnull;
}
/** Desde PHP 5.1.0 */
public function__isset($name)
{
echo"¿Está definido '$name'?\n";
return isset($this->data[$name]);
}
/** Desde PHP 5.1.0 */
public function__unset($name)
{
echo"Eliminando '$name'\n";
unset($this->data[$name]);
}
/** No es un método mágico, esta aquí para completar el ejemplo. */
public functiongetHidden()
{
return$this->hidden;
}
}
echo"<pre>\n";
$obj= newPropertyTest;
$obj->a=1;
echo$obj->a."\n\n";
var_dump(isset($obj->a));
unset($obj->a);
var_dump(isset($obj->a));
echo"\n";
echo$obj->declared."\n\n";
echo"Vamos a probar con la propiedad privada que se llama 'hidden':\n";
echo"Las propiedades privadas pueden consultarse en la clase, por lo que no se usa __get()...\n";
echo$obj->getHidden() ."\n";
echo"Las propiedades privadas no son visibles fuera de la clase, por lo que se usa __get()...\n";
echo$obj->hidden."\n";
?>El resultado del ejemplo sería:
Estableciendo 'a' a '1' Consultando 'a' 1 ¿Está definido 'a'? bool(true) Eliminando 'a' ¿Está definido 'a'? bool(false) 1 Vamos a probar con la propiedad privada que se llama 'hidden': Las propiedades privadas pueden consultarse en la clase, por lo que no se usa __get()... 2 Las propiedades privadas no son visibles fuera de la clase, por lo que se usa __get()... Consultando 'hidden' Notice: Propiedad indefinida mediante __get(): hidden en <file> en la línea 69 in <file>en la línea 28
__call()es lanzado al invocar un método inaccesible en un contexto de objeto.
__callStatic()es lanzado al invocar un método inaccesible en un contexto estático.
El parámetro$namecorresponde al nombre del método al que se está llamando. El parámetro$argumentses un array enumerado que contiene los parámetros que se han pasado al método$name.
Ejemplo #2 Sobrecarga de métodos mediante los métodos__call()and__callStatic()
<?php
classMethodTest
{
public function__call($name,$arguments)
{
// Nota: el valor $name es sensible a mayúsculas.
echo"Llamando al método de objeto '$name' "
.implode(', ',$arguments)."\n";
}
/** Desde PHP 5.3.0 */
public static function__callStatic($name,$arguments)
{
// Nota: el valor $name es sensible a mayúsculas.
echo"Llamando al método estático '$name' "
.implode(', ',$arguments)."\n";
}
}
$obj= newMethodTest;
$obj->runTest('en contexto de objeto');
MethodTest::runTest('en contexto estático');// Desde PHP 5.3.0
?>El resultado del ejemplo sería:
Llamando al método de objeto 'runTest' en contexto de objeto Llamando al método estático 'runTest' en contexto estático
PHP 5 ofrece una manera para definir objetos, por lo que es posible recorrer una lista de elementos con, por ejemplo, una sentenciaforeach. Por defecto, se utilizarán todas las propiedadesvisiblespara la iteración.
Ejemplo #1 Iteración simple de un objeto
<?php
classMiClase
{
public$var1='valor 1';
public$var2='valor 2';
public$var3='valor 3';
protected$protected='variable protegida';
private$private='variable privada';
functioniterateVisible() {
echo"MiClase::iterateVisible:\n";
foreach ($thisas$clave=>$valor) {
print"$clave=>$valor\n";
}
}
}
$clase= newMiClase();
foreach($claseas$clave=>$valor) {
print"$clave=>$valor\n";
}
echo"\n";
$clase->iterateVisible();
?>El resultado del ejemplo sería:
var1 => valor 1 var2 => valor 2 var3 => valor 3 MiClase::iterateVisible: var1 => valor 1 var2 => valor 2 var3 => valor 3 protected => variable protegida private => variable privada
Como se muestra en la salida,foreachrecorre todas las propiedadesvisiblesa las que se pueden acceder.
Para dar un paso más, se puede implementar lainterfazIterator. Esto permite al objeto decidir cómo será iterado y qué valores estarán disponibles en cada iteración.
Ejemplo #2 Iteración de un objeto implementando Iterator
<?php
classMiIteradorimplementsIterator
{
private$var= array();
public function__construct($array)
{
if (is_array($array)) {
$this->var=$array;
}
}
public functionrewind()
{
echo"rebobinando\n";
reset($this->var);
}
public functioncurrent()
{
$var=current($this->var);
echo"actual:$var\n";
return$var;
}
public functionkey()
{
$var=key($this->var);
echo"clave:$var\n";
return$var;
}
public functionnext()
{
$var=next($this->var);
echo"siguiente:$var\n";
return$var;
}
public functionvalid()
{
$clave=key($this->var);
$var= ($clave!==NULL&&$clave!==FALSE);
echo"válido:$var\n";
return$var;
}
}
$valores= array(1,2,3);
$it= newMiIterador($valores);
foreach ($itas$a=>$b) {
print"$a:$b\n";
}
?>El resultado del ejemplo sería:
rebobinando válido: 1 actual: 1 clave: 0 0: 1 siguiente: 2 válido: 1 actual: 2 clave: 1 1: 2 siguiente: 3 válido: 1 actual: 3 clave: 2 2: 3 siguiente: válido:
LainterfazIteratorAggregatese puede usar como alternativa para implementar todos los métodos deIterator.IteratorAggregatesolamente requiere la implementación de un único método,IteratorAggregate::getIterator(), el cual debería devolver una instancia de una clase que implementeIterator.
Ejemplo #3 Iteración de un objeto implementando IteratorAggregate
<?php
classMiColecciónimplementsIteratorAggregate
{
private$items= array();
private$cuenta=0;
// Se requiere la definición de la interfaz IteratorAggregate
public functiongetIterator() {
return newMiIterador($this->items);
}
public functionadd($valor) {
$this->items[$this->cuenta++] =$valor;
}
}
$colección= newMiColección();
$colección->add('valor 1');
$colección->add('valor 2');
$colección->add('valor 3');
foreach ($colecciónas$clave=>$val) {
echo"clave/valor: [$clave->$val]\n\n";
}
?>El resultado del ejemplo sería:
rebobinando actual: valor 1 válido: 1 actual: valor 1 clave: 0 clave/valor: [0 -> valor 1] siguiente: valor 2 actual: valor 2 válido: 1 actual: valor 2 clave: 1 clave/valor: [1 -> valor 2] siguiente: valor 3 actual: valor 3 válido: 1 actual: valor 3 clave: 2 clave/valor: [2 -> valor 3] siguiente: actual: válido:
Nota:
Para más ejemplos de iteradores, véase laextensión SPL.
Nota:
Los usuarios de PHP 5.5 y posteriores pueden investigar losgeneradores, los cuales posibilitan una forma alternativa de definir iteradores.
Los métodos mágicos son métodos especiales que sobreescriben acciones por defecto cuando se realizan ciertas acciones sobre un objeto.
Todos los nombres de los métodos que comienzan con__son reservados por PHP. Por lo tanto, se recomienda que no utilice los nombres de métodos a menos que se sobreescriba el comportamiento de PHP.
Los siguientes nombres de métodos se consideran mágicos:__construct(),__destruct(),__call(),__callStatic(),__get(),__set(),__isset(),__unset(),__sleep(),__wakeup(),__serialize(),__unserialize(),__toString(),__invoke(),__set_state(),__clone(), and__debugInfo().
Todos los métodos mágicos, a excepción de__construct(),__destruct(), y__clone(),deben serdeclarados comopúblico, en caso contrario se emite unE_WARNING. Antes de PHP 8.0.0, no se emitía ningún diagnóstico para los métodos mágicos__sleep(),__wakeup(),__serialize(),__unserialize(), y__set_state().
Si se utilizan tipo de declaraciones usados en la definición de un método mágico, deben ser idénticas a la firma descrita en este documento. De lo contrario, se emite un error fatal. Antes de PHP 8.0.0, no se emitía ningún diagnóstico. Sin embargo,__construct()y__destruct()no debe declarar un tipo de retorno; de lo contrario se emite un error fatal.
serialize()comprueba si la clase tiene un método con el nombre mágico__sleep(). Si es así, el método se ejecuta antes de cualquier serialización. Se puede limpiar el objeto y se supone que devuelve un array con los nombres de todas las variables de el objeto que se va a serializar. Si el método no devuelve nada, entoncesnulles serializado y un errorE_NOTICEes emitido.
Nota:
No es posible para__sleep()devolver nombres de propiedades privadas en las clases padres. Hacer esto resultaría un nivel de error
E_NOTICE. En su lugar, puede utilizar la interfazSerializable.
El uso para el que está destinado__sleep()consiste en confirmar datos pendientes o realizar tareas similares de limpieza. Además, el método es útil si tiene objetos muy grandes que no necesitan guardarse por completo.
Por el contrario,unserialize()comprueba la presencia de un método con el nombre mágico__wakeup(). Si está presente, este método puede reconstruir cualquier recurso que el objeto pueda tener.
El uso para el que está destinado__wakeup()es restablecer las conexiones de base de datos que se puedan haber perdido durante la serialización y realizar otras tareas de reinicialización.
Ejemplo #1 Sleep y wakeup
<?php
classConnection
{
protected$link;
private$dsn,$username,$password;
public function__construct($dsn,$username,$password)
{
$this->dsn=$dsn;
$this->username=$username;
$this->password=$password;
$this->connect();
}
private functionconnect()
{
$this->link= newPDO($this->dsn,$this->username,$this->password);
}
public function__sleep()
{
return array('dsn','username','password');
}
public function__wakeup()
{
$this->connect();
}
}?>$data):voidserialize()comprueba si la clase tiene una función mágica con el nombre__serialize(). Si es así, esa función se ejecuta antes de cualquier serialización. Debe construir y devolver un array asociativo de pares clave/valor que representen la forma serializada del objeto. Si no se devuelve ningún array, se lanzará una claseTypeError.
Nota:
Si tanto__serialize()y__sleep()están definidos en el mismo objeto, sólo se llamará a__serialize().__sleep()será ignorado. Si el objeto implementa la interfazSerializableel método
serialize()de la interfaz será ignorado y se utilizará__serialize()en su lugar.
El uso previsto de__serialize()es definir una representación arbitraria del objeto que sea fácil de serializar. Los elementos de la matriz pueden corresponder a propiedades del objeto, pero no es necesario.
Por el contrario,unserialize()comprueba la presencia de una función con el nombre mágico__unserialize(). Si está presente, a esta función se le pasará el array restaurado que fue devuelto por__serialize(). Entonces puede restaurar las propiedades del objeto desde ese array según sea apropiado.
Nota:
Si tanto__unserialize()y__wakeup()son definidos en el mismo objeto, sólo se llamará a__unserialize().__wakeup()será ignorado.
Nota:
Esta función está disponible a partir de PHP 7.4.0.
Ejemplo #2 Serialize y unserialize
<?php
classConnection
{
protected$link;
private$dsn,$username,$password;
public function__construct($dsn,$username,$password)
{
$this->dsn=$dsn;
$this->username=$username;
$this->password=$password;
$this->connect();
}
private functionconnect()
{
$this->link= newPDO($this->dsn,$this->username,$this->password);
}
public function__serialize(): array
{
return [
'dsn'=>$this->dsn,
'user'=>$this->username,
'pass'=>$this->password,
];
}
public function__unserialize(array$data):void
{
$this->dsn=$data['dsn'];
$this->username=$data['user'];
$this->password=$data['pass'];
$this->connect();
}
}?>El método__toString()permite a una clase decidir cómo comportarse cuando se le trata como un string. Por ejemplo, lo queecho $obj;mostraría. Este método debe devolver un string, si no se emitirá un nivel de error fatalE_RECOVERABLE_ERROR.
As of PHP 8.0.0, the return value follows standard PHP type semantics, meaning it will be coerced into astringif possible and ifstrict typingis disabled.
As of PHP 8.0.0, any class that contains a__toString()method will also implicitly implement theStringableinterface, and will thus pass type checks for that interface. Explicitly implementing the interface anyway is recommended.
In PHP 7.4, the returned valuemustbe astring, otherwise anErroris thrown.
Prior to PHP 7.4.0, the returned valuemustbe astring, otherwise a fatalE_RECOVERABLE_ERRORis emitted.
No se puede lanzar una excepción desde dentro un método__toString(). El método antes de PHP 7.4.0. Si lo hace, se producirá un error fatal.
Ejemplo #3 Ejemplo simple
<?php
// Declarar una clase simple
classTestClass
{
public$foo;
public function__construct($foo)
{
$this->foo=$foo;
}
public function__toString()
{
return$this->foo;
}
}
$class= newTestClass('Hola Mundo');
echo$class;
?>El resultado del ejemplo sería:
Hola Mundo
Antes de PHP 5.2.0 el método__toString()se llama sólo cuando se combina directamente conechooprint. Desde PHP 5.2.0, se le llama en cualquier contexto de string (e.j. enprintf()con el modificador%s) pero no en el contexto de otros tipos (e.j. con el modificador%d). Desde PHP 5.2.0, la conversión de los objetos sin el método__toString()a string podría causarE_RECOVERABLE_ERROR.
El método__invoke()es llamado cuando un script intenta llamar a un objeto como si fuera una función.
Nota:
Esta característica está disponible desde PHP 5.3.0.
Ejemplo #4 Uso de__invoke()
<?php
classCallableClass
{
public function__invoke($x)
{
var_dump($x);
}
}
$obj= newCallableClass;
$obj(5);
var_dump(is_callable($obj));
?>El resultado del ejemplo sería:
int(5) bool(true)
$properties):objectEste métodostatices llamado para las clases exportadas porvar_export().
El único parámetro de este método es un array que contiene las propiedades exportadas en la forma['property' => value, ...].
Ejemplo #5 Uso de__set_state()
<?php
classA
{
public$var1;
public$var2;
public static function__set_state($an_array)
{
$obj= newA;
$obj->var1=$an_array['var1'];
$obj->var2=$an_array['var2'];
return$obj;
}
}
$a= newA;
$a->var1=5;
$a->var2='foo';
$b=var_export($a,true);
var_dump($b);
eval('$c = '.$b.';');
var_dump($c);
?>El resultado del ejemplo sería:
string(60) "A::__set_state(array(
'var1' => 5,
'var2' => 'foo',
))"
object(A)#2 (2) {
["var1"]=>
int(5)
["var2"]=>
string(3) "foo"
}
Nota:Al exportar un objeto,var_export()no comprueba si__set_state()está implementado por la clase del objeto, por lo que la reimportación de tales objetos dará lugar a una excepciónError, si __set_state() no está implementado. En particular, esto afecta a algunas clases internas.Es responsabilidad del programador verificar que solamente se vayan a reimportar los objetos cuya clase implemente __set_state().
Este método es invocado porvar_dump()al volcar un objeto para obtener las propiedades que deberían mostrarse. Si el método no está definido sobre un objeto, se mostrarán todas las propiedades públicas protegidas y privadas.
Ejemplo #6 Utilizar__debugInfo()
<?php
classC{
private$prop;
public function__construct($val) {
$this->prop=$val;
}
public function__debugInfo() {
return [
'propSquared'=>$this->prop**2,
];
}
}
var_dump(newC(42));
?>El resultado del ejemplo sería:
object(C)#1 (1) {
["propSquared"]=>
int(1764)
}
PHP 5 introduce la nueva palabra clave final, que impide que las clases hijas sobrescriban un método, antecediendo su definición confinal. Si la propia clase se define como final, entonces no se podrá heredar de ella.
Ejemplo #1 Ejemplo de métodos Final
<?php
classBaseClass{
public functiontest() {
echo"llamada a BaseClass::test()\n";
}
final public functionmoreTesting() {
echo"llamada a BaseClass::moreTesting()\n";
}
}
classChildClassextendsBaseClass{
public functionmoreTesting() {
echo"llamada a ChildClass::moreTesting()\n";
}
}
// Devuelve un error Fatal: Cannot override final method BaseClass::moreTesting()
?>Ejemplo #2 Ejemplo de clase Final
<?php
final classBaseClass{
public functiontest() {
echo"llamada a BaseClass::test()\n";
}
// Aquí no importa si definimos una función como final o no
final public functionmoreTesting() {
echo"llamada a BaseClass::moreTesting()\n";
}
}
classChildClassextendsBaseClass{
}
// Devuelve un error Fatal: Class ChildClass may not inherit from final class (BaseClass)
?>Nota:Las propiedades y las constantes no pueden declararse como final. Sólo pueden las clases y los métodos.
No siempre se desea crear una copia de un objeto replicando todas sus propiedades completamente. Un buen ejemplo que ilustra la necesidad de contar con un constructor de copias, sería si tuviéramos un objeto que represente una ventana en GTK y el objeto almacene los recursos de esta ventana GTK, de forma que cuando creas un duplicado el comportamiento esperado sería una nueva ventana con las mismas propiedades, y que el nuevo objeto referencie a los recursos de la nueva ventana. Otro ejemplo es si un objeto hace referencia a otro objeto necesario, de forma que cuando se realiza una réplica del objeto principal, se espera que se cree una nueva instancia de este otro objeto, de forma que la réplica tenga su propia copia.
Para crear una copia de un objeto se utiliza la palabra claveclone(que invoca, si fuera posible, al método__clone()del objeto). No se puede llamar al método__clone()de un objeto directamente.
$copia_de_objeto = clone $objeto;
Cuando se clona un objeto, PHP llevará a cabo una copia superficial de las propiedades del objeto. Las propiedades que sean referencias a otras variables, mantendrán las referencias.
Una vez que la clonación ha finalizado, se llamará al método__clone()del nuevo objeto (si el método__clone()estuviera definido), para permitirle realizar los cambios necesarios sobre sus propiedades.
Ejemplo #1 Clonación de un objeto
<?php
classSubObject
{
static$instances=0;
public$instance;
public function__construct() {
$this->instance= ++self::$instances;
}
public function__clone() {
$this->instance= ++self::$instances;
}
}
classMyCloneable
{
public$object1;
public$object2;
function__clone()
{
// Forzamos la copia de this->object, si no
// hará referencia al mismo objeto.
$this->object1= clone$this->object1;
}
}
$obj= newMyCloneable();
$obj->object1= newSubObject();
$obj->object2= newSubObject();
$obj2= clone$obj;
print("Objeto Original:\n");
print_r($obj);
print("Objeto Clonado:\n");
print_r($obj2);
?>El resultado del ejemplo sería:
Objeto Original:
MyCloneable Object
(
[object1] => SubObject Object
(
[instance] => 1
)
[object2] => SubObject Object
(
[instance] => 2
)
)
Objeto Clonado:
MyCloneable Object
(
[object1] => SubObject Object
(
[instance] => 3
)
[object2] => SubObject Object
(
[instance] => 2
)
)
PHP 7.0.0 introdujo la posibilidad de acceder a un miembro del objeto recién clonado en una única expresión:
Ejemplo #2 Acceder a un miembre del objeto recién clonado
<?php
$dateTime= newDateTime();
echo (clone$dateTime)->format('Y');
?>El resultado del ejemplo sería algo similar a:
2016
Al utilizar el operador de comparación (==), se comparan de una forma sencilla las variables de cada objeto, es decir: dos instancias de un objeto son iguales si tienen los mismos atributos y valores (los valores se comparan con==), y son instancias de la misma clase.
Cuando se utiliza el operador identidad (===), las variables de un objeto son idénticas sí y sólo sí hacen referencia a la misma instancia de la misma clase.
Un ejemplo aclarará estas reglas.
Ejemplo #1 Ejemplo de comparación de objetos en PHP 5
<?php
functionbool2str($bool)
{
if ($bool===false) {
return'FALSO';
} else {
return'VERDADERO';
}
}
functioncompararObjetos(&$o1, &$o2)
{
echo'o1 == o2 : '.bool2str($o1==$o2) ."\n";
echo'o1 != o2 : '.bool2str($o1!=$o2) ."\n";
echo'o1 === o2 : '.bool2str($o1===$o2) ."\n";
echo'o1 !== o2 : '.bool2str($o1!==$o2) ."\n";
}
classBandera
{
public$bandera;
function__construct($bandera=true) {
$this->bandera=$bandera;
}
}
classOtraBandera
{
public$bandera;
function__construct($bandera=true) {
$this->bandera=$bandera;
}
}
$o= newBandera();
$p= newBandera();
$q=$o;
$r= newOtraBandera();
echo"Dos instancias de la misma clase\n";
compararObjetos($o,$p);
echo"\nDos referencias a la misma instancia\n";
compararObjetos($o,$q);
echo"\nInstancias de dos clases diferentes\n";
compararObjetos($o,$r);
?>El resultado del ejemplo sería:
Dos instancias de la misma clase o1 == o2 : VERDADERO o1 != o2 : FALSO o1 === o2 : FALSO o1 !== o2 : VERDADERO Dos referencias a la misma instancia o1 == o2 : VERDADERO o1 != o2 : FALSO o1 === o2 : VERDADERO o1 !== o2 : FALSO Instancias de dos clases diferentes o1 == o2 : FALSO o1 != o2 : VERDADERO o1 === o2 : FALSO o1 !== o2 : VERDADERO
Nota:
Las extensiones pueden definir sus propias reglas para la comparación de sus objetos (
==).
Desde su versión 5.3.0, PHP incorpora una nueva funcionalidad llamada enlace estático en tiempo de ejecución ("late static bindings" en inglés) que permite referirse referencias a la clase invocada en un contexto de herencia estática.
De forma más precisa, un enlace estático en tiempo de ejecución funciona almacenando el nombre de clase de la última llamada que no tenga «propagación». En el caso de llamadas a métodos estáticos, se trata de la clase nombrada explícitamente (normalmente la que precede al operador::); en los casos de llamadas a métodos no estáticos, es clase del objeto. Una «llamada con propagación» es una llamada estática que precedida porself::,parent::,static::, o, siguiendo la jerarquía de clases,forward_static_call(). La funciónget_called_class()puede utilizarse para obtener una cadena con el nombre de la clase invocada, ystatic::revela cuál es su alcance.
A esta funcionalidad se le ha llamado «enlace estático en tiempo de ejecución» teniendo en cuenta un punto de vista interno. «Enlace en tiempo de ejecución» viene del hecho de questatic::no será resuelto usando la clase donde el método está definido, sino que en su lugar se calculará utilizando información en tiempo de ejecución. También se le llamó «enlace estático» debido a que se puede utilizar (entre otras cosas) para llamadas a métodos estáticos.
self::Las referencias estáticas a la clase en uso, comoself::o__CLASS__, se resuelven empleando la clase a la que pertenece la función:
Ejemplo #1 Uso deself::
<?php
classA{
public static functionwho() {
echo__CLASS__;
}
public static functiontest() {
self::who();
}
}
classBextendsA{
public static functionwho() {
echo__CLASS__;
}
}
B::test();
?>El resultado del ejemplo sería:
A
Los enlaces estáticos en tiempo de ejecución tratan de resolver esta limitación empleando una palabra reservada que se refiera a la clase invocada inicialmente en tiempo de ejecución; básicamente, una palabra reservada que permita referirse a aBdesdetest(), según el ejemplo anterior. Se decidió no crear una nueva palabra reservada, si no utilizar en su lugarstatic, que ya era reservada.
Ejemplo #2 Uso básico destatic::
<?php
classA{
public static functionwho() {
echo__CLASS__;
}
public static functiontest() {
static::who();// He aquí el enlace estático en tiempo de ejecución
}
}
classBextendsA{
public static functionwho() {
echo__CLASS__;
}
}
B::test();
?>El resultado del ejemplo sería:
B
Nota:
En contextos no estáticos, la clase invocada será la clase de la instancia del objeto. Dado que
$this->trata de invocar métodos privados desde su mismo ámbito, el uso destatic::puede dar diferentes resultados. Otra diferencia es questatic::sólo puede referirse a propiedades estáticas.
Ejemplo #3 Uso destatic::en un contexto no estático
<?php
classA{
private functionfoo() {
echo"¡Éxito!\n";
}
public functiontest() {
$this->foo();
static::foo();
}
}
classBextendsA{
/* foo() se copiará en B, por lo tanto su ámbito seguirá siendo A
* y la llamada tendrá éxito */
}
classCextendsA{
private functionfoo() {
/* se reemplaza el método original; el ámbito del nuevo es ahora C */
}
}
$b= newB();
$b->test();
$c= newC();
$c->test();//falla
?>El resultado del ejemplo sería:
¡Éxito! ¡Éxito! ¡Éxito! Fatal error: Call to private method C::foo() from context 'A' in /tmp/test.php on line 9
Nota:
En una llamada que se resuelva como estática, la resolución de enlaces estáticos en tiempo de ejecución se detendrá sin propagarse. Por otra parte, las llamadas estáticas que utilicen palabras reservadas como
parent::oself::sí propagarán la información de llamada.Ejemplo #4 Llamadas que propagan y que no propagan la información de llamada
<?php
classA{
public static functionfoo() {
static::who();
}
public static functionwho() {
echo__CLASS__."\n";
}
}
classBextendsA{
public static functiontest() {
A::foo();
parent::foo();
self::foo();
}
public static functionwho() {
echo__CLASS__."\n";
}
}
classCextendsB{
public static functionwho() {
echo__CLASS__."\n";
}
}
C::test();
?>El resultado del ejemplo sería:
A C C
Uno de los puntos clave de la POO de PHP 5 que a menudo se menciona es que "por omisión los objetos se pasan por referencia". Esto no es completamente cierto. Esta sección rectifica esa creencia general, usando algunos ejemplos.
Una referencia en PHP es un alias, que permite a dos variables diferentes escribir sobre un mismo valor. Desde PHP 5, una variable de tipo objeto ya no contiene el objeto en sí como valor. Únicamente contiene un identificador del objeto que le permite localizar al objeto real. Cuando se pasa un objeto como parámetro, o se devuelve como retorno, o se asigna a otra variable, las distintas variables no son alias: guardan una copia del identificador, que apunta al mismo objeto.
Ejemplo #1 Referencias y Objetos
<?php
classA{
public$foo=1;
}
$a= newA;
$b=$a;// $a y $b son copias del mismo identificador
// ($a) = ($b) = <id>
$b->foo=2;
echo$a->foo."\n";
$c= newA;
$d= &$c;// $c y $d son referencias
// ($c,$d) = <id>
$d->foo=2;
echo$c->foo."\n";
$e= newA;
functionfoo($obj) {
// ($obj) = ($e) = <id>
$obj->foo=2;
}
foo($e);
echo$e->foo."\n";
?>El resultado del ejemplo sería:
2 2 2
La funciónserialize()devuelve un string que contiene un flujo de bytes que representa cualquier valor que se pueda almacenar en PHP. Por otra parte,unserialize()puede restaurar los valores originales a partir de dicho string. Al utilizar serialize para guardar un objeto, almacenará todas las variables de dicho objeto. En cambio los métodos no se guardarán, sólo el nombre de la clase.
Para poder deserializar (unserialize()) un objeto, debe estar definida la clase de ese objeto. Es decir, si se tiene un objeto de la clase A, y lo serializamos, se obtendrá un string que haga referencia a la clase A y contenga todas las variables que haya en esta clase. Si se desea deserializar en otro fichero, antes debe estar presente la definición de la clase A. Esto se puede hacer, por ejemplo, escribiendo la definición de la clase A en un fichero, para después o bien incluirlo, o bien hacer uso de la funciónspl_autoload_register().
<?php
// classa.inc:
classA{
public$one=1;
public functionshow_one() {
echo$this->one;
}
}
// page1.php:
include("classa.inc");
$a= newA;
$s=serialize($a);
// almacenamos $s en algún lugar en el que page2.php puede encontrarlo.
file_put_contents('store',$s);
// page2.php:
// se necesita para que unserialize funcione correctamente.
include("classa.inc");
$s=file_get_contents('store');
$a=unserialize($s);
// now use the function show_one() of the $a object.
$a->show_one();
?>Si una aplicación está usando sesiones, y utilizasession_register()para registrar objetos, estos objetos se serializarán automáticamente al final de cada página PHP, y se deserializan también automáticamente en cada una de las siguientes peticiones. Esto significa que, una vez que formen parte de la sesión, estos objetos se podrán utilizar en cualquier página de la aplicación. Sin embargo, la funciónsession_register(): ha sido borrada a partir de PHP 5.4.0
Si una aplicación serializa objetos para su uso posterior, se recomienda encarecidamente que se incluya la definición de la clase en toda la aplicación. Si no se hiciera, se deserializaría el objeto sin una definición de clase, lo cual daría como resultado que PHP definiera al objeto con la clase__PHP_Incomplete_Class_Name, que no tiene métodos, haciendo que el objeto no fuera útil.
Por tanto, si en el ejemplo anterior$ase guardara en una sesión mediantesession_register("a"), sería necesario incluir el ficheroclassa.incen todas las páginas, no sólo enpage1.phpypage2.php.
Más allá del consejo de arriba, observe que también se puede conectar con eventos de serialización y deserialización sobre un objeto usando los métodos__sleep()y__wakeup(). El uso de__sleep()también permite serializar únicamente un subconjunto de propiedades de objetos.
En PHP 7.2.0, se introdujo la contravarianza parcial mediante la eliminación de las restricciones de tipo en los parámetros de un método hijo. A partir de PHP 7.4.0, se añadió soporte completo de covarianza y contravarianza.
La covarianza permite que el método hijo devuelva un tipo más específico que el tipo de devolución del método de su padre. Mientras que la contravarianza permite que un tipo de parámetro sea menos específico en un método hijo, que el de su padre.
Para ilustrar cómo funciona la covarianza, una simple clase de padre abstracta,Animales creada.Animalse extenderá a las clases hijo,Cat, yDog.
<?php
abstract classAnimal
{
protectedstring $name;
public function__construct(string $name)
{
$this->name=$name;
}
abstract public functionspeak();
}
classDogextendsAnimal
{
public functionspeak()
{
echo$this->name." barks";
}
}
classCatextendsAnimal
{
public functionspeak()
{
echo$this->name." meows";
}
}Observe que no hay ningún método que devuelva valores en este ejemplo. Unas pocas fábricas que devuelven un nuevo objeto de tipo claseAnimal,Cat, oDog.
<?php
interfaceAnimalShelter
{
public functionadopt(string $name):Animal;
}
classCatShelterimplementsAnimalShelter
{
public functionadopt(string $name):Cat// instead of returning class type Animal, it can return class type Cat
{
return newCat($name);
}
}
classDogShelterimplementsAnimalShelter
{
public functionadopt(string $name):Dog// instead of returning class type Animal, it can return class type Dog
{
return newDog($name);
}
}
$kitty= (newCatShelter)->adopt("Ricky");
$kitty->speak();
echo"\n";
$doggy= (newDogShelter)->adopt("Mavrick");
$doggy->speak();El resultado del ejemplo sería:
Ricky meows Mavrick barks
Continuando con el ejemplo anterior con las clasesAnimal,Cat, yDog, una clase llamadaFoodyAnimalFoodserán incluidas, y un métodoeat(AnimalFood $food)es añadido a la clase abstractaAnimal.
<?php
classFood{}
classAnimalFoodextendsFood{}
abstract classAnimal
{
protectedstring $name;
public function__construct(string $name)
{
$this->name=$name;
}
public functioneat(AnimalFood $food)
{
echo$this->name." eats ".get_class($food);
}
}Para ver el comportamiento de la contravención, el métodoeatse sobrescribe en la claseDogpara permitir cualquier tipo de objetoFood. La claseCatpermanece sin cambios.
<?php
classDogextendsAnimal
{
public functioneat(Food $food) {
echo$this->name." eats ".get_class($food);
}
}El siguiente ejemplo mostrará el comportamiento de la contravarianza.
<?php
$kitty= (newCatShelter)->adopt("Ricky");
$catFood= newAnimalFood();
$kitty->eat($catFood);
echo"\n";
$doggy= (newDogShelter)->adopt("Mavrick");
$banana= newFood();
$doggy->eat($banana);El resultado del ejemplo sería:
Ricky eats AnimalFood Mavrick eats Food
¿Pero qué pasa si el (gatito)$kittytrata de (comer)eatla$banana?
$kitty->eat($banana);El resultado del ejemplo sería:
Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given
Aquí se registran los cambios del modelo de POO de PHP 5. Las descripciones y otras notas respecto a estas nuevas funcionalidades están documentadas dentro de la documentación de POO 5.
| Versión | Descripción |
|---|---|
| 7.0.0 | Definir propiedades (compatibles) en dos rasgos («traits») ya no lanza un error. |
| 5.6.0 | Añadido: El método__debugInfo(). |
| 5.5.0 | Añadido: La constante mágica::class. |
| 5.5.0 | Añadido:finallypara manejar excepciones. |
| 5.4.0 | Añadido:traits. |
| 5.4.0 | Cambiado: Si una claseabstractadefine una firma para el constructor, ahora se hará cumplir. |
| 5.3.3 | Cambiado: Los métodos con el mismo nombre que el último elemento de un nombre de clase perteneciente a unespacio de nombresya no serán tratados como unconstructor. Este cambio no afecta a las clases que no pertenecen a un espacio de nombres. |
| 5.3.0 | Cambiado: Ya no es necesario que los valores predeterminados de los métodos de una clase que implemente un interfaz coincidan con los valores predeterminados de los prototipos de la interfaz. |
| 5.3.0 | Cambiado: Ahora es posible hacer referencia a la clase utilizando una variable (p.ej.,echo $nombreclase::constante;). La variable no puede contener como valor una palabra reservada (p.ej.,self,parentostatic). |
| 5.3.0 | Cambiado: Se emite un error de nivelE_WARNINGsi alsobrecargarun método mágico se le declara comoestático. Además, hace necesario que tenga visibilidad pública. |
| 5.3.0 | Cambiado: Antes de 5.3.0, las excepciones lanzadas en la función__autoload()no podían capturarse en el bloquecatch, y provocaban un error fatal. Ahora, las excepciones lanzadas dentro de la función __autoload pueden capturarse en el bloquecatch, con una única salvedad: Si se lanza una excepción definida por el usuario, esta excepción debería estar disponible. Se puede utilizar recursivamente la función __autoload para cargar automáticamente la clase de la excepción definida por el usuario. |
| 5.3.0 | Añadido: El método__callStatic. |
| 5.3.0 | Añadido: El soporte paraheredocynowdocparaconstantesde clase y definición de propiedades. Nota: los valores heredoc deben seguir las mismas reglas que los string de comillas dobles (p.ej., no contener variables). |
| 5.3.0 | Añadido:Enlaces estáticos en tiempo de ejecución. |
| 5.3.0 | Añadido: El método__invoke(). |
| 5.2.0 | Cambiado: Al método__toString()sólo se le invocaba cuando se le combinaba conechoo conprint. Pero ahora, se le invoca en cualquier contexto de string (p.ej, enprintf()con el modificador%s) pero no en contextos de otro tipo (p.ej. con el modificador%d). Desde PHP 5.2.0, convertir objetos a string sin el método__toStringemitirá un error de nivelE_RECOVERABLE_ERROR. |
| 5.1.3 | Cambiado: En versiones anteriores de PHP 5, se consideraba obsoleto el uso devary emitía un error de nivelE_STRICT. Ya no está obsoleto, y por tanto no emite el error. |
| 5.1.0 | Cambiado: Ahora se invoca al método estático__set_state()en las clases exportadas porvar_export(). |
| 5.1.0 | Añadido: Los métodos__isset()y__unset(). |
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
¿Qué son los espacios de nombres? En su definición más aceptada, los espacios de nombres son una manera de encapsular elementos. Se pueden ver como un concepto abstracto en muchos aspectos. Por ejemplo, en cualquier sistema operativo, los directorios sirven para agrupar ficheros relacionados, actuando así como espacios de nombres para los ficheros que contienen. Como ejemplo, el ficherofoo.txtpuede existir en los directorios/home/gregy/home/otro, pero no pueden coexistir dos copias defoo.txten el mismo directorio. Además, para acceder al ficherofoo.txtfuera del directorio/home/greg, se debe anteponer el nombre del directorio al nombre del fichero, empleando el separador de directorios para así obtener/home/greg/foo.txt. Este mismo principio se extiende a los espacios de nombres en el mundo de la programación.
| Versión | Descripción |
|---|---|
| 7.0.0 | Añadidas las Declaraciones de use en grupo. |
En el mundo de PHP, los espacios de nombres están diseñados para solucionar dos problemas con los que se encuentran los autores de bibliotecas y de aplicaciones al crear elementos de código reusable, tales como clases o funciones:
Los espacios de nombres de PHP proporcionan una manera para agrupar clases, interfaces, funciones y constantes relacionadas. Un ejemplo de la sintaxis de los espacios de nombres de PHP:
Ejemplo #1 Ejemplo de sintaxis de espacios de nombres
<?php
namespacemi\nombre;// véase la sección "Definir espacios de nombres"
classMiClase{}
functionmifunción() {}
constMICONSTANTE=1;
$a= newMiClase;
$c= new \mi\nombre\MiClase;// véase la sección "Espacio global"
$a=strlen('hola');// véase la sección "Utilizar espacios de nombres: una
// alternativa a funciones/constantes globales"
$d= namespace\MICONSTANTE;// véase la sección "El operador namespace y
// la constante __NAMESPACE__"
$d=__NAMESPACE__.'\MICONSTANTE';
echoconstant($d);// véase la sección "Espacios de nombres y características dinámicas del lenguaje"
?>Nota:
Los nombres de los espacios de nombres
PHPyphp, y los nombres compuestos a partir de estos (comoPHP\Classes) están reservados para el uso interno del lenguaje y no deben utilizarse en el código del espacio del usuario.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Aunque cualquier código de PHP válido puede estar contenido dentro de un espacio de nombres, solamente se ven afectados por espacios de nombres los siguientes tipos de código: clases (incluyendo abstractas y traits), interfaces, funciones y constantes.
Los espacios de nombres se declaran utilizando la palabra reservadanamespace. Un fichero que contenga un espacio de nombres debe declararlo al inicio del mismo, antes que cualquier otro código, con una excepción: la palabra reservadadeclare.
Ejemplo #1 Declarar un único espacio de nombres
<?php
namespaceMiProyecto;
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
?>declarepara declarar la codificación de un fichero fuente. Además, todo lo que no sea código de PHP no puede preceder a la declaración del espacio de nombres, incluyendo espacios en blanco extra:Ejemplo #2 Declarar un único espacio de nombres
<html>
<?php
namespaceMiProyecto;// error fatal - el espacio de nombres debe ser la primera sentencia del script
?>También, a diferencia de otras construcciones de PHP, se puede definir el mismo espacio de nombres en varios ficheros, permitiendo la separación del contenido de un espacio de nombres a través del sistema de ficheros.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Al igual que los directorios y ficheros, los espacios de nombres de PHP también tienen la capacidad de especificar una jerarquía de nombres de espacios de nombres. Así, un nombre de un espacio de nombres se puede definir con subniveles:
Ejemplo #1 Declarar un único espacio de nombres con jerarquía
<?php
namespaceMiProyecto\Sub\Nivel;
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
?>MiProyecto\Sub\Nivel\CONECTAR_OK, la claseMiProyecto\Sub\Nivel\Conexióny la funciónMiProyecto\Sub\Nivel\conectar.(PHP 5 >= 5.3.0, PHP 7, PHP 8)
También se pueden declarar varios espacios de nombres en un mismo fichero. Se permiten dos tipos de sintaxis.
Ejemplo #1 Declarar varios espacios de nombres, sintaxis de combinación simple
<?php
namespaceMiProyecto;
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
namespaceOtroProyecto;
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
?>No se recomienda esta sintaxis para combinar espacios de nombres en un único fichero. En su lugar, se recomienda emplear la sintaxis de llaves alternativa.
Ejemplo #2 Declarar varios espacios de nombres, sintaxis de llaves
<?php
namespaceMiProyecto{
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
}
namespaceOtroProyecto{
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
}
?>Se desaconseja completamente, como práctica de código, la combinación de varios espacios de nombres en un mismo fichero. El caso de uso principal es combinar varios scripts de PHP en el mismo fichero.
Combinar código global que no es de espacio de nombres con código que sí lo es, sólo está soportado mediante la sintaxis de llaves. El código global debería estar encerrado en una declaración de espacio de nombres sin nombre de espacio de nombres:
Ejemplo #3 Declarar múltiples espacios de nombres y código que no es de espacio de nombres
<?php
namespaceMiProyecto{
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
}
namespace {// código global
session_start();
$a=MiProyecto\conectar();
echoMiProyecto\Conexión::iniciar();
}
?>No puede existir código de PHP fuera de las llaves del espacio de nombres, excepto para una sentencia de apertura 'declare'.
Ejemplo #4 Declarar varios espacios de nombres y código que no es de espacio de nombres
<?php
declare(encoding='UTF-8');
namespaceMiProyecto{
constCONECTAR_OK=1;
classConexión{/* ... */}
functionconectar() {/* ... */}
}
namespace {// código global
session_start();
$a=MiProyecto\conectar();
echoMiProyecto\Conexión::iniciar();
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Antes de hablar del uso de los espacios de nombres es importante entender cómo sabe PHP qué elemento del código del espacio de nombres se requiere. Se puede hacer una simple analogía entre los espacios de nombres de PHP y el sistema de ficheros. Existen tres maneras de acceder a un fichero en el sistema de ficheros:
foo.txt. Se resuelve condirectorio_actual/foo.txtdonde directorio_actual es el directorio actualmente ocupado. Así, si el directorio actual es/home/foo, el nombre se resuelve con/home/foo/foo.txt.subdirectorio/foo.txt. Se resuelve condirectorioactual/subdirectorio/foo.txt./main/foo.txt. Se resuelve con/main/foo.txt.$a = new foo();ofoo::método_estático();. Si el espacio de nombres actual esespacio_de_nombres_actual, esto se resuelve conespacio_de_nombres_actual\foo. Si el código es global, es decir, no es de espacio de nombres, esto se resuelve confoo.Una advertencia: los nombres no cualificados para funciones y constantes se resolverán con funciones y constantes globales si la función o la constante del espacio de nombres no está definida. VéaseUtilizar espacios de nombres: una alternativa a funciones/constantes globalespara más detalles.$a = new subespacio_de_nombres\foo();osubespacio_de_nombres\foo::método_estático();. Si el espacio de nombres actual esespacio_de_nombres_actual, esto se resuelve conespacio_de_nombres_actual\subespacio_de_nombres\foo. Si el código es global, es decir, no es de espacio de nombres, esto se resuelve consubespacio_de_nombres\foo.$a = new \espacio_de_nombres_actual\foo();o\espacio_de_nombres_actual\foo::método_estático();. Esto siempre se resuelve con nombre literal especificado en el código,espacio_de_nombres_actual\foo.Un ejemplo de los tres tipos de sintaxis en código real:
fichero1.php
<?php
namespaceFoo\Bar\subespacio_de_nombres;
constFOO=1;
functionfoo() {}
classfoo
{
static functionmétodo_estático() {}
}
?>fichero2.php
<?php
namespaceFoo\Bar;
include'fichero1.php';
constFOO=2;
functionfoo() {}
classfoo
{
static functionmétodo_estático() {}
}
/* Nombre no cualificado */
foo();// se resuelve con la función Foo\Bar\foo
foo::método_estático();// se resuelve con la clase Foo\Bar\foo, método método_estático
echoFOO;// se resuelve con la constante Foo\Bar\FOO
/* Nombre cualificado */
subespacio_de_nombres\foo();// se resuelve con la función Foo\Bar\subespacio_de_nombres\foo
subespacio_de_nombres\foo::método_estático();// se resuelve con la clase Foo\Bar\subespacio_de_nombres\foo,
// método método_estático
echosubespacio_de_nombres\FOO;// se resuelve con la constante Foo\Bar\subespacio_de_nombres\FOO
/* Nombre conmpletamente cualificado */
\Foo\Bar\foo();// se resuelve con la función Foo\Bar\foo
\Foo\Bar\foo::método_estático();// se resuelve con la clase Foo\Bar\foo, método método_estático
echo \Foo\Bar\FOO;// se resuelve con la constante Foo\Bar\FOO
?>Observe que para acceder a cualquier clase, función o constante globales, se puede utilizar un nombre completamente cualificado, como\strlen()o\Exceptiono\INI_ALL.
Ejemplo #1 Acceder a clases, funciones y constantes globales desde un espacio de nombres
<?php
namespaceFoo;
functionstrlen() {}
constINI_ALL=3;
classException{}
$a= \strlen('hola');// llama a la función global strlen
$b= \INI_ALL;// accede a la constante global INI_ALL
$c= new \Exception('error');// instancia a la clase global Exception
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
La implementación de PHP de los espacios de nombres está influenciada por su naturaleza dinámica como lenguaje de programación. Así, para convertir código como el del siguiente ejemplo en código de espacios de nombres:
Ejemplo #1 Acceder dinámicamente a elementos
ejemplo1.php:
<?php
classnombre_clase
{
function__construct()
{
echo__METHOD__,"\n";
}
}
functionnombre_func()
{
echo__FUNCTION__,"\n";
}
constnombre_const="global";
$a='nombre_clase';
$obj= new$a;// imprime nombre_clase::__construct
$b='nombre_func';
$b();// imprime nombre_func
echoconstant('nombre_const'),"\n";// imprime global
?>Ejemplo #2 Acceder dinámicamente a elementos de un espacio de nombres
<?php
namespacenombre_espacio_de_nombres;
classnombre_clase
{
function__construct()
{
echo__METHOD__,"\n";
}
}
functionnombre_func()
{
echo__FUNCTION__,"\n";
}
constnombre_const="de espacio de nombres";
/* observe que si se emplean comillas dobles, se debe usar "\\nombre_espacio_de_nombres\\nombre_clase" */
$a='\nombre_espacio_de_nombres\nombre_clase';
$obj= new$a;// imprime nombre_espacio_de_nombres\nombre_clase::__construct
$a='nombre_espacio_de_nombres\nombre_clase';
$obj= new$a;// también imprime nombre_espacio_de_nombres\nombre_clase::__construct
$b='nombre_espacio_de_nombres\nombre_func';
$b();// imprime nombre_espacio_de_nombres\nombre_func
$b='\nombre_espacio_de_nombres\nombre_func';
$b();// también imprime nombre_espacio_de_nombres\nombre_func
echoconstant('\nombre_espacio_de_nombres\nombre_const'),"\n";// imprime de espacio de nombres
echoconstant('nombre_espacio_de_nombres\nombre_const'),"\n";// también imprime de espacio de nombres
?>Asegúrese de leer lanota sobre escapar nombres de espacios de nombres en cadenas.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
PHP admite dos formas de acceder de manera abstracta a elementos dentro del espacio de nombres actual: la constante mágica__NAMESPACE__, y la palabra reservadanamespace.
El valor de__NAMESPACE__es una cadena que contiene el nombre del espacio de nombres actual. En código global, que no es de espacio de nombres, contiene una cadena vacía.
Ejemplo #1 Ejemplo de __NAMESPACE__, código de espacio de nombres
<?php
namespaceMiProyecto;
echo'"',__NAMESPACE__,'"';// imprime "MiProyecto"
?>Ejemplo #2 Ejemplo de __NAMESPACE__, código global
<?php
echo'"',__NAMESPACE__,'"';// imprime ""
?>__NAMESPACE__es útil para construir nombres dinámicamente, por ejemplo:Ejemplo #3 Empleo de __NAMESPACE__ para la construcción dinámica de nombres
<?php
namespaceMiProyecto;
functionobtener($nombre_clase)
{
$a=__NAMESPACE__.'\\'.$nombre_clase;
return new$a;
}
?>La palabra reservadanamespacese puede utilizar para solicitar explícitamente un elemento del espacio de nombres o subespacio de nombres actual. Es el equivalente del espacio de nombres para el operadorselfde las clases.
Ejemplo #4 El operador namespace, dentro de un espacio de nombres
<?php
namespaceMiProyecto;
useblah\blahasmío;// véase "Uso de los espacios de nombres: Apodar/Importar"
blah\mío();// llama a la función MiProyecto\blah\mío()
namespace\blah\mío();// llama a la función MiProyecto\blah\mío()
namespace\func();// llama a la función MiProyecto\func()
namespace\sub\func();// llama a la función MiProyecto\sub\func()
namespace\nombrec::método();// llama al método estático "método" de la clase MiProyecto\nombrec
$a= new namespace\sub\nombrec();// instancia un objeto de la clase MiProyecto\sub\nombrec
$b= namespace\CONSTANTE;// asigna el valor de la constante MiProyecto\CONSTANTE a $b
?>Ejemplo #5 El operador namespace, en código global
<?php
namespace\func();// llama a la función func()
namespace\sub\func();// llama a la función sub\func()
namespace\nombrec::método();// llama al método estático "método" de la clase nombrec
$a= new namespace\sub\nombrec();// instancia un objeto de la clase sub\nombrec
$b= namespace\CONSTANTE;// asigna el valor de la constante CONSTANTE a $b
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
La capacidad de referirse a un nombre completamente cualificado externo con un alias, o importar, es una característca importante de los espacios de nombres. Esto es similar a la capacidad de los sistemas de ficheros basados en Unix de crear enlaces simbólicos a un fichero o directorio.
Todas las versiones de PHP que tienen soporte para espacios de nombres admiten tres tipos de alias o importación: apodar un nombre de clase, apodar un nombre de interfaz, y apodar un nombre de espacio de nombres. PHP 5.6+ también permite apodar o importar nombres de funciones y constantes.
En PHP, la acción de apodar se lleva a cabo con el operadoruse. Aquí hay un ejemplo que muestra los cinco tipos de importación:
Ejemplo #1 Importar/apodar con el operador use
<?php
namespacefoo;
useMi\Completo\NombreDeClaseasOtra;
// esto es lo mismo que utilizar Mi\Completo\NombreEN as NombreEN
useMi\Completo\NombreEN;
// importar una clase global
useArrayObject;
// importar una función (PHP 5.6+)
use functionMi\Completo\nombreDeFunción;
// apodar una función (PHP 5.6+)
use functionMi\Completo\nombreDeFunciónasfunc;
// importar una constante (PHP 5.6+)
use constMi\Completa\CONSTANTE;
$obj= new namespace\Otra;// instancia un objeto de la clase foo\Otra
$obj= newOtra;// instancia un objeto de la clase class Mi\Completo\NombreDeClase
NombreEN\suben\func();// llama a la función Mi\Completo\NombreEN\subes\func
$a= newArrayObject(array(1));// instancia un objeto de la clase ArrayObject
// sin el "use ArrayObject" instanciaríamos un objeto de la clase foo\ArrayObject
func();// llama a la función Mi\Completo\nombreDeFunción
echoCONSTANT;// imprime el valor de Mi\Completa\CONSTANTE;
?>Foo\Bar, en oposición a los nombres globales que no lo contienen, comoFooBar), no es necesaria y no está recomendada la barra invertida inicial, ya que los nombres importados deben ser completamente cualificados, por lo que no son procesados en relación al espacio de nombres actual.PHP admite además un atajo para poner varias sentencias use en la misma línea
Ejemplo #2 Importar/apodar con el operador use, varias sentencias use combinadas
<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;
$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
NombreEN\suben\func();// llama a la función Mi\Completo\NombreEN\suben\func
?>La importación se realiza durante la compilación, por lo que no afecta a los nombres de clases, funciones o constantes.
Ejemplo #3 La importación y los nombres dinámicos
<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;
$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
$a='Otra';
$obj= new$a;// instancia un objeto de la clase Otra
?>Además, la importación sólo afecta a los nombres cualificados y no cualificados. Los nombres completamente cualificados son absolutos, por lo que no se ven afectados por la importación.
Ejemplo #4 La importación y los nombres completamente cualificados
<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;
$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
$obj= new \Otra;// instancia un objeto de la clase Otra
$obj= newOtra\cosa;// instancia un objeto de la clase Mi\Completo\NombreDeClase\cosa
$obj= new \Otra\cosa;// instancia un objeto de la clase Otra\cosa
?>La palabra reservadausedebe ser declarada en el ámbito exterior de un fichero (el ámbito global) o dentro de declaraciones de espacios de nombres. Esto es así debido a que la importación se realiza durante la compilación y no durante la ejecución, por lo que no puede ser utilizada en un ámbito de bloque. El siguiente ejemplo muestra un uso ilegal de la palabra reservadause:
Ejemplo #5 Regla de importación ilegal
<?php
namespaceIdiomas;
functionaGroenlandés
{
useIdiomas\Danés;
// ...
}
?>Nota:
Las reglas de importación tiene una base por fichero, lo que significa que los ficheros incluidosNOheredarán las reglas de importación del padre.
useen grupoDesde PHP 7.0 en adelante, las clases, funciones y constantes importadas desde el mismonamespacepueden ser agrupadas en una única sentenciause.
<?php
// Código anterir a PHP 7
useun\espacioDeNombres\ClaseA;
useun\espacioDeNombres\ClaseB;
useun\espacioDeNombres\ClaseCasC;
use functionun\espacioDeNombres\fn_a;
use functionun\espacioDeNombres\fn_b;
use functionun\espacioDeNombres\fn_c;
use constun\espacioDeNombres\ConstA;
use constun\espacioDeNombres\ConstB;
use constun\espacioDeNombres\ConstC;
// Código de PHP 7+
useun\espacioDeNombres\{ClaseA,ClaseB,ClaseCasC};
use functionun\espacioDeNombres\{fn_a,fn_b,fn_c};
use constun\espacioDeNombres\{ConstA,ConstB,ConstC};(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Sin ninguna definición de espacios de nombres, todas las definiciones de clases y funciones son colocadas en el espacio global, como si lo estuvieran antes de que PHP soportara los espacios de nombres. Prefijar un nombre con\especificará que el nombre es requerido desde el espacio global incluso en el contexto del espacio de nombres.
Ejemplo #1 Usar la especificación de espacio global
<?php
namespaceA\B\C;
/* Esta función es A\B\C\fopen */
functionfopen() {
/* ... */
$f= \fopen(...);// llamar a fopen global
return$f;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Dentro de un espacio de nombres, cuando PHP se encuentra con nombre no cualificado en un contexto de nombre de clase, función o constante, lo resuelve con diferentes prioridades. Los nombres de clases siempre se resuelven con el nombre de espacio de nombres actual. Así, para acceder a clases de usuario internas o que no son de espacio de nombres, se debe referir a ellas con su nombre completamente cualificado:
Ejemplo #1 Acceder a clases globales dentro de un espacio de nombres
<?php
namespaceA\B\C;
classExceptionextends \Exception{}
$a= newException('hola');// $a es un objeto de la clase A\B\C\Exception
$b= new \Exception('hola');// $b es un objeto de la clase Exception
$c= newArrayObject;// error fatal, no se encontró la clase A\B\C\ArrayObject
?>Para funciones y constantes, PHP recurrirá a funciones y constantes globales si no existe una función o constante en el espacio de nombres.
Ejemplo #2 Recurrir a funciones/constantes globales dentro de un espacio de nombres
<?php
namespaceA\B\C;
constE_ERROR=45;
functionstrlen($str)
{
return \strlen($str) -1;
}
echoE_ERROR,"\n";// imprime "45"
echoINI_ALL,"\n";// imprime "7" - recurre a INI_ALL global
echostrlen('hola'),"\n";// imprime "3"
if (is_array('hola')) {// imprime "no es un array"
echo"es una array\n";
} else {
echo"no es un array\n";
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
A continuación se exponen unas definiciones importantes para estas reglas de resolución:
Es un identificador sin un separador de espacios de nombres, comoFoo
Es un identificador con un separador de espacios de nombres, comoFoo\Bar
Es un identificador con un separador de espacios de nombres que comienza con un separador de espacios de nombres, como\Foo\Bar.namespace\Footambién es un nombre completamente cualificado.
Los nombres se resuelven siguiendo estas reglas de resolución:
new \A\Bse resuelve con la claseA\B.A\B\Cse importa comoC, una llamada aC\D\e()se traduce comoA\B\C\D\e().C\D\e()se lleva a cabo dentro del espacio de nombresA\B, se traduce comoA\B\C\D\e().A\B\Cse importa como C,new C()se traduce comonew A\B\C().foo():A\B\foo().foo().A\B), las llamadas a nombres de clases no cualificados o cualificados (no los completamente cualificados) se resuelven durante la ejecución. Así se resuelve una llamada anew C()o anew D\E(). Paranew C():A\B\C.A\B\C.new D\E():A\B\D\E.A\B\D\E.new \C().Ejemplo #1 Las resoluciones de nombres ilustradas
<?php
namespaceA;
useB\D,C\EasF;
// llamadas a funciones
foo();// primero se intenta llamar a "foo" definida en el espacio de nombres "A"
// después se llama a la función global "foo"
\foo();// se llama a la función "foo" definidia en el ámbito global
mi\foo();// se llama a la función "foo" definida en el espacio de nombres "A\mi"
F();// primero se intenta llamar a "F" definida en el espacio de nombres "A"
// después se llama a la función global "F"
// referecias a clases
newB();// crea un objeto de la clase "B" definida en el espacio de nombres "A"
// si no se encuentra, se intenta autocargar la clase "A\B"
newD();// usando las reglas de importación, se crea un objeto de la clase "D" definida en el espacio de nombres "B"
// si no se encuentra, se intenta autocargar la clase "B\D"
newF();// usando las reglas de importación, se crea un objeto de la clase "E" definida en el espacio de nombres "C"
// si no se encuentra, se intenta autocargar la clase "C\E"
new \B();// crea un objeto de la clase "B" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "B"
new \D();// crea un objeto de la clase "D" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "D"
new \F();// crea un objeto de la clase "F" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "F"
// métodos estáticos y funciones de un espacio de nombres desde otro espacio de nombres
B\foo();// se llama a la función "foo" desde el espacio de nombres "A\B"
B::foo();// se llama al método "foo" de la clase "B" definidia en el espacio de nombres "A"
// si no se encuentra la clase "A\B", se intenta autocargar la clase "A\B"
D::foo();// usando las reglas de importación, se llama al método "foo" de la clase "D" definida en el espacio de nombres "B"
// si no se encuentra la clase "B\D", se intenta autocargar la clase "B\D"
\B\foo();// se llama a la función "foo" desde el espacio de nombres "B"
\B::foo();// se llama al método "foo" de la clase "B" desde el ámbito global
// si no es encuentra la clase "B", se intenta autocargar la clase "B"
// métodos estáticos yfunciones de un espacio de nombres del espacio de nombres actual
A\B::foo();// se llama al método "foo" de la clase "B" desde el espacio de nombres "A\A"
// si no se encuentra la clase "A\A\B", se intenta autocargar la clase "A\A\B"
\A\B::foo();// se llama al método "foo" de la clase "B" desde el espacio de nombres "A"
// si no se encuentra la clase "A\B", se intenta autocargar la clase "A\B"
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Esta sección está dividida en dos subsecciones: preguntas comunes, y algunas especificaciones de implementación que son útiles para comprender completamente los espacios de nombres.
Primero, las preguntas comunes.
\mi\nombreo\nombre?mi\nombre?nombre?nombre?Existen unos pocos detalles de las implementaciones de espacios de nombres que son útiles para enterderlos.
use.No. Los espacios de nombres no afectan a ningún código existente de ninguna manera, o a ningún código todavía por escribir que no contenga espacios de nombres. Se puede escribir este código si se desea:
Ejemplo #1 Acceder a clases globales fuera de un espacio de nombres
<?php
$a= new \stdClass;
?>Esto es funcionalmente equivalente a:
Ejemplo #2 Acceder a clases globales fuera de un espacio de nombres
<?php
$a= newstdClass;
?>Ejemplo #3 Acceder a clases internas en espacios de nombres
<?php
namespacefoo;
$a= new \stdClass;
functionprobar(\ArrayObject $ejemploalusiónatipo=null) {}
$a= \DirectoryIterator::CURRENT_AS_FILEINFO;
// extender una clase interna o global
classMiExcepciónextends \Exception{}
?>Ejemplo #4 Acceder a clases, funciones o constantes internas en un espacio de nombres
<?php
namespacefoo;
classMiClase{}
// usar una clase desde el espacio de nombres actual como una declaración de tipo
functionprobar(MiClase $ejemploalusiónatipo=null) {}
// otra manera de usar una clase desde el espacio de nombres actual una declaración de tipo
functionprobar(\foo\MiClase $ejemploalusiónatipo=null) {}
// extender una clase desde el espacio de nombres actual
classExtendidaextendsMiClase{}
// acceder a una función global
$a= \funcglobal();
// acceder a una constante global
$b= \INI_ALL;
?>\mi\nombreo\nombre?Los nombres que comienzan con una\siempre se resuelven a aquello a lo que se asemejan, así\mi\nombrede hecho esmi\nombre, y\ExceptionesException.
Ejemplo #5 Nombres completamente cualificados
<?php
namespacefoo;
$a= new \mi\nombre();// instancia a la clase "mi\nombre"
echo \strlen('hola');// llama a la función "strlen"
$a= \INI_ALL;// $a está establecida al valor de la constante "INI_ALL"
?>mi\nombre?Los nombres que contienen una barra invertida pero no comienzan con una barra invertida comomi\nombrepueden resolverse de dos formas diferentes.
Si hay una sentencia de importación que apode a otro nombre comomi, el alias de importación se aplica amienmi\nombre.
De lo contrario, al nombre del espacio de nombres actual se le anteponemi\nombre.
Ejemplo #6 Nombres cualificados
<?php
namespacefoo;
useblah\blahasfoo;
$a= newmi\nombre();// instancia a la clase "foo\mi\nombre"
foo\bar::nombre();// llama a método estático "nombre" de la clase "blah\blah\bar"
mi\bar();// llama a la función "foo\mi\bar"
$a=mi\BAR;// establece $a al valor de la constante "foo\mi\BAR"
?>nombre?Los nombres de clases que no contienen una barra invertida comonombrese pueden resolver de dos formas diferentes.
Si hay una sentencia de importación que apode a otro nombre comonombre, se aplica el alias de importación.
De lo contrario, al nombre del espacio de nombres actual se le anteponenombre.
Ejemplo #7 Nombres de clases no cualificados
<?php
namespacefoo;
useblah\blahasfoo;
$a= newnombre();// instancia a la clase "foo\nombre"
foo::nombre();// llama al método estático "nombre" de la clase "blah\blah"
?>nombre?Los nombres de funciones o de constantes que no contienen una barra invertida comonombrese pueden resolver de dos formas diferentes.
Primero, al nombre del espacio de nombres actual se le anteponenombre.
Finalmente, si elnombrede la constante o de la función no existe en el espacio de nombres actual, se emplea unnombrede constante o función global, si es que existe.
Ejemplo #8 Nombres de funciones o constantes no cualificados
<?php
namespacefoo;
useblah\blahasfoo;
constFOO=1;
functionmi() {}
functionfoo() {}
functionsort(&$a)
{
\sort($a);// invoca a la función global "sort"
$a=array_flip($a);
return$a;
}
mi();// calls "foo\mi"
$a=strlen('hola');// llama a la función global "strlen" ya que "foo\strlen" no existe
$array= array(1,3,2);
$b=sort($array);// llama a la función "foo\sort"
$c=foo();// llama a la función "foo\foo" - la importación no se aplica
$a=FOO;// establece $a al valor de la constante "foo\FOO"; la importación no se aplica
$b=INI_ALL;// establece $b al valor de la constante "INI_ALL"
?>Están permitidas las siguientes combinaciones de scripts:
fichero1.php
<?php
namespacemis\cosas;
classMiClase{}
?>otro.php
<?php
namespaceotro;
classcosa{}
?>fichero2.php
<?php
namespacemis\cosas;
include'fichero1.php';
include'otro.php';
useotro\cosaasMiClase;
$a= newMiClase;// instancia a la clase "cosa" del espacio de nombres otro
?>No existe conflicto entre nombres, aunque la claseMiClaseexista dentro del espacio de nombresmis\cosas, porque la definición de MiClase está en otro fichero. Sin embargo, el siguiente ejemplo causa un error fatal por el conflicto entre nombres, debido a que MiClase está definida en el mismo fichero que el de la sentencia use.
<?php
namespacemis\cosas;
useotro\cosaasMiClase;
classMiClase{}// error fatal: MiClase entra en conflicto con la sentencia de importación
$a= newMiClase;
?>PHP no permite los espacios de nombres anidados
<?php
namespacemis\cosas{
namespaceanidado{
classfoo{}
}
}
?><?php
namespacemis\cosas\anidado{
classfoo{}
}
?>use.Ants de PHP 5.6, los únicos elementos que se ven afectados por la sentenciauseson los espacios de nombres y los nombres de clases. Para abreviar una constante o una función larga, se ha de importar el espacio de nombres que la contiene:
<?php
namespacemío;
usenombre\en\ultra\largo;
$a=largo\CONSTANT;
largo\func();
?>Es muy importante darse cuenta de que, debeido a que la barra invertida se usa como carácter de escape dentro de cadenas, se deberían emplear dos barras inverticas cuando se utilicen dentro de cadenas. De lo contrario, existe el riesgo de obtener consecuencias inesperadas:
Ejemplo #9 Peligros de usar nombres de espacios de nombres dentro de una cadena entre comillas dobles
<?php
$a="peligroso\nombre";// ¡\n es una nueva línea dentro de las cadenas entre comillas dobles!
$obj= new$a;
$a='sin\peligro\alguno';// aquí sin problemas.
$obj= new$a;
?>Cualquier constante no definida que no sea cualificada, comoFOO, generará una aviso explicando que PHP asume queFOOes el valor de la constante. Cualquier constante, cualificada o completamente cualificada, que contenga una barra invertida producirá un error fatal si no se encuentra.
Ejemplo #10 Constantes no definidas
<?php
namespacebar;
$a=FOO;// produce un aviso - constante no definida "FOO" se asume que es "FOO";
$a= \FOO;// error fatal, constante FOO del espacio de nombres no definida
$a=Bar\FOO;// error fatal, constante bar\Bar\FOO del espacio de nombres no definida
$a= \Bar\FOO;// error fatal, constante Bar\FOO del espacio de nombres no definida
?>Cualquier intento de definir una constante de espacio de nombres que sea una constante especial interna, resultará en un error fatal:
Ejemplo #11 Constantes no definidas
<?php
namespacebar;
constNULL=0;// error fatal;
consttrue='estúpido';// también error fatal;
// etc.
?>(PHP 8 >= 8.1.0)
Enumerations, or "Enums" allow a developer to define a custom type that is limited to one of a discrete number of possible values. That can be especially helpful when defining a domain model, as it enables "making invalid states unrepresentable."
Enums appear in many languages with a variety of different features. In PHP, Enums are a special kind of object. The Enum itself is a class, and its possible cases are all single-instance objects of that class. That means Enum cases are valid objects and may be used anywhere an object may be used, including type checks.
The most popular example of enumerations is the built-in boolean type, which is an enumerated type with legal valuestrueandfalse. Enums allows developers to define their own arbitrarily robust enumerations.
Enums are similar to classes, and share the same namespaces as classes, interfaces, and traits. They are also autoloadable the same way. An Enum defines a new type, which has a fixed, limited number of possible legal values.
<?php
enum Suit
{
caseHearts;
caseDiamonds;
caseClubs;
caseSpades;
}
?>This declaration creates a new enumerated type namedSuit, which has four and only four legal values:Suit::Hearts,Suit::Diamonds,Suit::Clubs, andSuit::Spades. Variables may be assigned to one of those legal values. A function may be type checked against an enumerated type, in which case only values of that type may be passed.
<?php
functionpick_a_card(Suit $suit) { ... }
$val=Suit::Diamonds;
// OK
pick_a_card($val);
// OK
pick_a_card(Suit::Clubs);
// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
?>An Enumeration may have zero or morecasedefinitions, with no maximum. A zero-case enum is syntactically valid, if rather useless.
For Enumeration cases, the same syntax rules apply as to any label in PHP, seeConstants.
By default, cases are not intrinsically backed by a scalar value. That is,Suit::Heartsis not equal to"0". Instead, each case is backed by a singleton object of that name. That means that:
<?php
$a=Suit::Spades;
$b=Suit::Spades;
$a===$b;// true
$ainstanceofSuit;// true
?>It also means that enum values are never<or>each other, since those comparisons are not meaningful on objects. Those comparisons will always returnfalsewhen working with enum values.
This type of case, with no related data, is called a "Pure Case." An Enum that contains only Pure Cases is called a Pure Enum.
All Pure Cases are implemented as instances of their enum type. The enum type is represented internally as a class.
All Cases have a read-only property,name, that is the case-sensitive name of the case itself.
<?php
printSuit::Spades->name;
// prints "Spades"
?>It is also possible to use thedefined()andconstant()functions to check for the existence of or read an enum case if the name is obtained dynamically. This is, however, discouraged as usingBacked enumsshould work for most use cases.
By default, Enumerated Cases have no scalar equivalent. They are simply singleton objects. However, there are ample cases where an Enumerated Case needs to be able to round-trip to a database or similar datastore, so having a built-in scalar (and thus trivially serializable) equivalent defined intrinsically is useful.
To define a scalar equivalent for an Enumeration, the syntax is as follows:
<?php
enum Suit:string
{
caseHearts='H';
caseDiamonds='D';
caseClubs='C';
caseSpades='S';
}
?>A case that has a scalar equivalent is called a Backed Case, as it is "Backed" by a simpler value. An Enum that contains all Backed Cases is called a "Backed Enum." A Backed Enum may contain only Backed Cases. A Pure Enum may contain only Pure Cases.
A Backed Enum may be backed by types ofintorstring, and a given enumeration supports only a single type at a time (that is, no union ofint|string). If an enumeration is marked as having a scalar equivalent, then all cases must have a unique scalar equivalent defined explicitly. There are no auto-generated scalar equivalents (e.g., sequential integers). Backed cases must be unique; two backed enum cases may not have the same scalar equivalent. However, a constant may refer to a case, effectively creating an alias. SeeEnumeration constants.
Equivalent values must be literals or literal expressions. Constants and constant expressions are not supported. That is,1 + 1is allowed, but1 + SOME_CONSTis not.
Backed Cases have an additional read-only property,value, which is the value specified in the definition.
<?php
printSuit::Clubs->value;
// Prints "C"
?>In order to enforce thevalueproperty as read-only, a variable cannot be assigned as a reference to it. That is, the following throws an error:
<?php
$suit=Suit::Clubs;
$ref= &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>Backed enums implement an internalBackedEnuminterface, which exposes two additional methods:
from(int|string): selfwill take a scalar and return the corresponding Enum Case. If one is not found, it will throw aValueError. This is mainly useful in cases where the input scalar is trusted and a missing enum value should be considered an application-stopping error.tryFrom(int|string): ?selfwill take a scalar and return the corresponding Enum Case. If one is not found, it will returnnull. This is mainly useful in cases where the input scalar is untrusted and the caller wants to implement their own error handling or default-value logic.Thefrom()andtryFrom()methods follow standard weak/strong typing rules. In weak typing mode, passing an integer or string is acceptable and the system will coerce the value accordingly. Passing a float will also work and be coerced. In strict typing mode, passing an integer tofrom()on a string-backed enum (or vice versa) will result in aTypeError, as will a float in all circumstances. All other parameter types will throw a TypeError in both modes.
<?php
$record=get_stuff_from_database($id);
print$record['suit'];
$suit=Suit::from($record['suit']);
// Invalid data throws a ValueError: "X" is not a valid scalar value for enum "Suit"
print$suit->value;
$suit=Suit::tryFrom('A') ??Suit::Spades;
// Invalid data returns null, so Suit::Spades is used instead.
print$suit->value;
?>Manually defining afrom()ortryFrom()method on a Backed Enum will result in a fatal error.
Enums (both Pure Enums and Backed Enums) may contain methods, and may implement interfaces. If an Enum implements an interface, then any type check for that interface will also accept all cases of that Enum.
<?php
interfaceColorful
{
public functioncolor():string;
}
enum SuitimplementsColorful
{
caseHearts;
caseDiamonds;
caseClubs;
caseSpades;
// Fulfills the interface contract.
public functioncolor():string
{
returnmatch($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
// Not part of an interface; that's fine.
public functionshape():string
{
return"Rectangle";
}
}
functionpaint(Colorful $c) { ... }
paint(Suit::Clubs);// Works
printSuit::Diamonds->shape();// prints "Rectangle"
?>In this example, all four instances ofSuithave two methods,color()andshape(). As far as calling code and type checks are concerned, they behave exactly the same as any other object instance.
On a Backed Enum, the interface declaration goes after the backing type declaration.
<?php
interfaceColorful
{
public functioncolor():string;
}
enum Suit:stringimplementsColorful
{
caseHearts='H';
caseDiamonds='D';
caseClubs='C';
caseSpades='S';
// Fulfills the interface contract.
public functioncolor():string
{
returnmatch($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
}
?>Inside a method, the$thisvariable is defined and refers to the Case instance.
Methods may be arbitrarily complex, but in practice will usually return a static value ormatchon$thisto provide different results for different cases.
Note that in this case it would be a better data modeling practice to also define aSuitColorEnum Type with values Red and Black and return that instead. However, that would complicate this example.
The above hierarchy is logically similar to the following class structure (although this is not the actual code that runs):
<?php
interfaceColorful
{
public functioncolor():string;
}
final classSuitimplementsUnitEnum,Colorful
{
public constHearts= newself('Hearts');
public constDiamonds= newself('Diamonds');
public constClubs= newself('Clubs');
public constSpades= newself('Spades');
private function__construct(publicreadonly string $name) {}
public functioncolor():string
{
returnmatch($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
public functionshape():string
{
return"Rectangle";
}
public static functioncases(): array
{
// Illegal method, because manually defining a cases() method on an Enum is disallowed.
// See also "Value listing" section.
}
}
?>Methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
Enumerations may also have static methods. The use for static methods on the enumeration itself is primarily for alternative constructors. E.g.:
<?php
enum Size
{
caseSmall;
caseMedium;
caseLarge;
public static functionfromLength(int $cm): static
{
returnmatch(true) {
$cm<50=> static::Small,
$cm<100=> static::Medium,
default => static::Large,
};
}
}
?>Static methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
Enumerations may include constants, which may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
An enum constant may refer to an enum case:
<?php
enum Size
{
caseSmall;
caseMedium;
caseLarge;
public constHuge=self::Large;
}
?>Enumerations may leverage traits, which will behave the same as on classes. The caveat is that traitsused in an enum must not contain properties. They may only include methods and static methods. A trait with properties will result in a fatal error.
<?php
interfaceColorful
{
public functioncolor():string;
}
traitRectangle
{
public functionshape():string{
return"Rectangle";
}
}
enum SuitimplementsColorful
{
useRectangle;
caseHearts;
caseDiamonds;
caseClubs;
caseSpades;
public functioncolor():string
{
returnmatch($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
}
?>Because cases are represented as constants on the enum itself, they may be used as static values in most constant expressions: property defaults, static variable defaults, parameter defaults, global and class constant values. They may not be used in other enum case values, but normal constants may refer to an enum case.
However, implicit magic method calls such asArrayAccesson enums are not allowed in static or constant definitions as we cannot absolutely guarantee that the resulting value is deterministic or that the method invocation is free of side effects. Function calls, method calls, and property access continue to be invalid operations in constant expressions.
<?php
// This is an entirely legal Enum definition.
enum DirectionimplementsArrayAccess
{
caseUp;
caseDown;
public functionoffsetGet($val) { ... }
public functionoffsetExists($val) { ... }
public functionoffsetSet($val) { throw newException(); }
public functionoffsetUnset($val) { throw newException(); }
}
classFoo
{
// This is allowed.
constBar=Direction::Down;
// This is disallowed, as it may not be deterministic.
constBar=Direction::Up['short'];
// Fatal error: Cannot use [] on enums in constant expression
}
// This is entirely legal, because it's not a constant expression.
$x=Direction::Up['short'];
?>Although Enums are built on classes and objects, they do not support all object-related functionality. In particular, Enum cases are forbidden from having state.
The following object functionality is available, and behaves just as it does on any other object:
TARGET_CLASStarget filter includes Enums themselves. TheTARGET_CLASS_CONSTtarget filter includes Enum Cases.__CLASS__and__FUNCTION__constants behave as normalThe::classmagic constant on an Enum type evaluates to the type name including any namespace, exactly the same as an object. The::classmagic constant on a Case instance also evaluates to the Enum type, as it is an instance of that type.
Additionally, enum cases may not be instantiated directly withnew, nor withReflectionClass::newInstanceWithoutConstructor()in reflection. Both will result in an error.
<?php
$clovers= newSuit();
// Error: Cannot instantiate enum Suit
$horseshoes= (newReflectionClass(Suit::class))->newInstanceWithoutConstructor()
// Error: Cannot instantiate enum Suit
?>Both Pure Enums and Backed Enums implement an internal interface namedUnitEnum.UnitEnumincludes a static methodcases().cases()returns a packed array of all defined Cases in the order of declaration.
<?php
Suit::cases();
// Produces: [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades]
?>Manually defining acases()method on an Enum will result in a fatal error.
Enumerations are serialized differently from objects. Specifically, they have a new serialization code,"E", that specifies the name of the enum case. The deserialization routine is then able to use that to set a variable to the existing singleton value. That ensures that:
<?php
Suit::Hearts===unserialize(serialize(Suit::Hearts));
printserialize(Suit::Hearts);
// E:11:"Suit:Hearts";
?>On deserialization, if an enum and case cannot be found to match a serialized value a warning will be issued andfalsereturned.
If a Pure Enum is serialized to JSON, an error will be thrown. If a Backed Enum is serialized to JSON, it will be represented by its value scalar only, in the appropriate type. The behavior of both may be overridden by implementingJsonSerializable.
Forprint_r(), the output of an enum case is slightly different from objects to minimize confusion.
<?php
enum Foo{
caseBar;
}
enum Baz:int{
caseBeep=5;
}
print_r(Foo::Bar);
print_r(Baz::Beep);
/* Produces
Foo Enum (
[name] => Bar
)
Baz Enum:int {
[name] => Beep
[value] => 5
}
*/
?>Classes have contracts on their methods:
<?php
classA{}
classBextendsA{}
functionfoo(A $a) {}
functionbar(B $b) {
foo($b);
}
?>This code is type-safe, as B follows the contract of A, and through the magic of co/contra-variance, any expectation one may have of the methods will be preserved, exceptions excepted.
Enums have contracts on their cases, not methods:
<?php
enum ErrorCode{
caseSOMETHING_BROKE;
}
functionquux(ErrorCode $errorCode)
{
// When written, this code appears to cover all cases
match($errorCode) {
ErrorCode::SOMETHING_BROKE=>true,
}
}
?>Thematchstatement in the functionquuxcan be static analyzed to cover all of the cases in ErrorCode.
But imagine it was allowed to extend enums:
<?php
// Thought experiment code where enums are not final.
// Note, this won't actually work in PHP.
enum MoreErrorCodeextendsErrorCode{
casePEBKAC;
}
functionfot(MoreErrorCode $errorCode) {
quux($errorCode);
}
fot(MoreErrorCode::PEBKAC);
?>Under normal inheritance rules, a class that extends another will pass the type check.
The problem would be that thematchstatement inquux()no longer covers all the cases. Because it doesn't know aboutMoreErrorCode::PEBKACthe match will throw an exception.
Because of this enums are final and can't be extended.
Ejemplo #1 Basic limited values
<?php
enum SortOrder
{
caseAsc;
caseDesc;
}
functionquery($fields,$filter,SortOrder $order=SortOrder::Asc) { ... }
?>Thequery()function can now proceed safe in the knowledge that$orderis guaranteed to be eitherSortOrder::AscorSortOrder::Desc. Any other value would have resulted in aTypeError, so no further error checking or testing is needed.
Ejemplo #2 Advanced exclusive values
<?php
enum UserStatus:string
{
casePending='P';
caseActive='A';
caseSuspended='S';
caseCanceledByUser='C';
public functionlabel():string
{
returnmatch($this) {
static::Pending=>'Pending',
static::Active=>'Active',
static::Suspended=>'Suspended',
static::CanceledByUser=>'Canceled by user',
};
}
}
?>In this example, a user's status may be one of, and exclusively,UserStatus::Pending,UserStatus::Active,UserStatus::Suspended, orUserStatus::CanceledByUser. A function can type a parameter againstUserStatusand then only accept those four values, period.
All four values have alabel()method, which returns a human-readable string. That string is independent of the "machine name" scalar equivalent string, which can be used in, for example, a database field or an HTML select box.
<?php
foreach (UserStatus::cases() as$case) {
printf('<option value="%s">%s</option>\n',$case->value,$case->label());
}
?>Desarfortunadamente, no importa lo cuidadoso que uno sea escribiendo código; los errores son un hecho de la vida. PHP notificará errores, advertencias y avisos para muchos problemas comunes de codificación y de tiempo de ejecución, por lo que saber cómo detectar y manejar estos errores hará la depuración mucho más sencilla.
PHP notifica errores en respuesta a varias condiciones de error internas. Estas se pueden utilizar para señalar varias condiciones diferentes, mostrándose y/o registrándose si fuera necesario.
Cada error que genera PHP incluye un tipo. Existe unalista de dichos tipos, junto con una breve descripción de su comportamiento y sus posibles causas.
Si no se establece un manejador de errores, PHP manejará cada error que ocurra según su configuración. Los errores que se notifican y los que se ignoran se controla mediante la directivaerror_reportingde php.ini, o durante la ejecución llamando aerror_reporting(). Sin embargo, se recomienda encarecidamente establecer la directiva de configuración, ya que algunos errores pueden ocurrir antes de comenzar la ejecución de un script.
En un entorno de desarrollo debería establecerse siempreerror_reportingaE_ALL, debido a que es necesario reconocer y corregir los problemas generados por PHP. En producción, se podría establecer esta directiva a un nivel de menor verbosidad comoE_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED, aunque en muchos casosE_ALLtambién es apropiado, ya que puede proporcionar advertencias precoces de problemas potenciales.
Lo que PHP hace con estos errores depende de dos directivas más de php.ini.display_errorscontrola si el error es mostrado como parte de la salida del script. Esta debería estar siempre deshabilitada en un entorno de producción, ya que puede incluir información confidencial tal como contraseñas de bases de datos, aunque a menudo es útil habilitarla en desarrollo debido a que asegura la notificación inmediata de problemas.
Además de mostrar errores, PHP puede registrarlos cuando la directivalog_errorsestá habilitada. Esta registrará cualquier error en el fichero o registro del sistema definido porerror_log. Esta directiva puede ser extremadamente útil en un entorno de producción debido a que se pueden registrar los errores que ocurran y generar informes basados en ellos.
Si el manejo de errores predeterminado de PHP es inadecuado, también se pueden manejar muchos tipos de error con un manejador de errores propio medianteset_error_handler(). Mientras que algunos tipos de error no se pueden manejar de esta forma, aquellos que sí se pueden lo hacen de la manera en que su script vea apropiada: por ejemplo, se puede emplear para mostrar al usuario una página de error personalizada y luego notificar más directamente mediante un registro, tal como el envío de un correo electrónico.
PHP 7 cambia la mayoría de los errores notificados por PHP. En lugar de notificar errores a través del mecanismo de notificación de errores tradicional de PHP 5, la mayoría de los errores ahora son notificados lanzando excepcionesError.
Al igual que las excepciones normales, las excepcionesErrorse propagarán hasta alcanzar el primer bloquecatchcoincidente. Si no hay bloques coincidentes, será invocado cualquier manejador de excepciones predeterminado instalado conset_exception_handler(), y si no hubiera ningún manejador de excepciones predeterminado, la excepción será convertida en un error fatal y será manejada como un error tradicional.
Debido a que la jerarquía deErrorno hereda deException, el código que emplee bloquescatch (Exception $e) { ... }para manejar excepciones no capturadas en PHP 5 encontrará que estosErrores no son capturados por dichos bloques. Se requiere, por tanto, un bloquecatch (Error $e) { ... }o un manejadorset_exception_handler().
Una clase de Excepción definida por el usuario puede ser definida ampliando la clase Exception interna. Los miembros y las propiedades de abajo muestran lo que es accesible dentro de la clase hija que deriva de la clase Exception interna.
Ejemplo #1 La clase Exception Interna
<?php
classException
{
protected$message='Unknown exception';// mensaje de excepción
private$string;// caché de __toString
protected$code=0;// código de excepción definido por el usuario
protected$file;// nombre de archivo fuente de la excepción
protected$line;// línea fuente de la excepción
private$trace;// determinación del origen
private$previous;// excepción previa si la excepción está anidada
public function__construct($message=null,$code=0,Exception $previous=null);
final private function__clone();// Inhibe la clonación de excepciones.
final public functiongetMessage();// mensaje de excepción
final public functiongetCode();// código de excepción
final public functiongetFile();// nombre de archivo fuente
final public functiongetLine();// línea fuente
final public functiongetTrace();// un array de backtrace()
final public functiongetPrevious();// excepción anterior
final public functiongetTraceAsString();// string formateado del seguimiento del origen
// Sobrescribible
public function__toString();// string formateado para mostrar
}
?>Si una clase extiende la clase Exception interna y redefine elconstructor, se recomienda encarecidamente que también llame aparent::__construct()para asegurarse que toda la información disponible haya sido asignada apropiadamente. El método__toString()puede ser sobrescrito para proporcionar una salida personalizada cuando el objeto es presentado como un string.
Nota:
Las excepciones no se pueden clonar. Intentarclonaruna Excepción resultará en un error
E_ERRORfatal.
Ejemplo #2 Extender la clase Exception (PHP 5.3.0+)
<?php
/**
* Definir una clase de excepción personalizada
*/
classMiExcepciónextendsException
{
// Redefinir la excepción, por lo que el mensaje no es opcional
public function__construct($message,$code=0,Exception $previous=null) {
// algo de código
// asegúrese de que todo está asignado apropiadamente
parent::__construct($message,$code,$previous);
}
// representación de cadena personalizada del objeto
public function__toString() {
return__CLASS__.": [{$this->code}]:{$this->message}\n";
}
public functionfunciónPersonalizada() {
echo"Una función personalizada para este tipo de excepción\n";
}
}
/**
* Crear una clase para probar la excepción
*/
classProbarExcepción
{
public$var;
constTHROW_NONE=0;
constTHROW_CUSTOM=1;
constTHROW_DEFAULT=2;
function__construct($avalue=self::THROW_NONE) {
switch ($avalue) {
caseself::THROW_CUSTOM:
// lanzar la excepción personalizada
throw newMiExcepción('1 no es un parámetro válido',5);
break;
caseself::THROW_DEFAULT:
// lanzar la predeterminada.
throw newException('2 no está permitido como parámetro',6);
break;
default:
// No hay excepción, el objeto se creará.
$this->var=$avalue;
break;
}
}
}
// Ejemplo 1
try {
$o= newProbarExcepción(ProbarExcepción::THROW_CUSTOM);
} catch (MiExcepción $e) {// Será atrapada
echo"Atrapada mi excepción\n",$e;
$e->funciónPersonalizada();
} catch (Exception $e) {// Skipped
echo"Atrapada la Excepción Predeterminada\n",$e;
}
// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";
// Ejemplo 2
try {
$o= newProbarExcepción(ProbarExcepción::THROW_DEFAULT);
} catch (MiExcepción $e) {// Este tipo no coincide
echo"Atrapada mi excepción\n",$e;
$e->funciónPersonalizada();
} catch (Exception $e) {// Will be caught
echo"Atrapada la Excepción Predeterminada\n",$e;
}
// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";
// Ejemplo 3
try {
$o= newProbarExcepción(ProbarExcepción::THROW_CUSTOM);
} catch (Exception $e) {// Será atrapada
echo"Atrapada la Excepción Predeterminada\n",$e;
}
// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";
// Ejemplo 4
try {
$o= newProbarExcepción();
} catch (Exception $e) {// Saltado, sin excepción
echo"Atrapada la Excepción Predeterminada\n",$e;
}
// Continuar la ejecución
var_dump($o);// ProbarExcepción
echo"\n\n";
?>Nota:
Las versiones de PHP 5, anteriores a PHP 5.3.0, no soportan excepciones anidadas. El siguiente fragmento de código se puede usar para reemplazar la clase MiExcepción si se desea ejecutar este ejemplo.
<?php
/**
* Definir una clase de excepción personalizada
*/
classMiExcepciónextendsException
{
// Redefinir la excepción, por lo que el mensaje no es opcional
public function__construct($message,$code=0) {
// algo de código
// asegúrese de que todo está asignador apropiadamente
parent::__construct($message,$code);
}
// representación de cadena personalizada del objeto
public function__toString() {
return__CLASS__.": [{$this->code}]:{$this->message}\n";
}
public functionfunciónPersonalizada() {
echo"Una función personalizada para este tipo de excepción\n";
}
}
?>
PHP 5 tiene un modelo de excepciones similar al de otros lenguajes de programación. Una excepción puede ser lanzada ("thrown"), y atrapada ("catched") dentro de PHP. El código puede estar dentro de un bloquetrypara facilitar la captura de excepciones potenciales. Cada bloquetrydebe tener al menos un bloquecatchofinallycorrespondiente.
El objeto lanzado debe ser una instancia de la claseExceptiono una subclase deException. Intentar lanzar un objeto que no lo sea resultará en un Error Fatal de PHP.
catchSe pueden usar múltiples bloquescatchpara atrapar diferentes clases de excepciones. La ejecución normal (cuando no es lanzada ninguna excepción dentro del bloquetry) continuará después del último bloquecatchdefinido en la sencuencia. Las excepciones pueden ser lanzadas ("thrown") (o relanzadas) dentro de un bloquecatch.
Cuando una excepción es lanzada, el código siguiente a la declaración no será ejecutado, y PHP intentará encontrar el primer bloquecatchcoincidente. Si una excepción no es capturada, se emitirá un Error Fatal de PHP con un mensaje "Uncaught Exception ..." ("Excepción No Capturada"), a menos que se haya definido un manejador conset_exception_handler().
finallyEn PHP 5.5 y posterior, se puede utilizar un bloquefinallydespués o en lugar de los bloquescatch. El código de dentro del bloquefinallysiempre se ejecutará después de los bloquestryycatch, independientemente de que se haya lanzado una excepción o no, y antes de que la ejecución normal continúe.
Nota:
Las funciones internas de PHP utilizan principalmente laInformación de Errores, sólo las extensionesOrientadas a objetosmodernas utilizan excepciones. Sin embargo, los errores se pueden traducir a excepciones simplemente conErrorException.
LaBiblioteca Estádar de PHP (SPL)proporciona un buen número deexcepciones internas.
Ejemplo #3 Lanzar una Excepción
<?php
functioninverso($x) {
if (!$x) {
throw newException('División por cero.');
}
return1/$x;
}
try {
echoinverso(5) ."\n";
echoinverso(0) ."\n";
} catch (Exception $e) {
echo'Excepción capturada: ',$e->getMessage(),"\n";
}
// Continuar la ejecución
echo'Hola Mundo\n';
?>El resultado del ejemplo sería:
0.2 Excepción capturada: División por cero. Hola Mundo
Ejemplo #4 Manejo de excepciones con un bloquefinally
<?php
functioninverse($x) {
if (!$x) {
throw newException('División por cero.');
}
return1/$x;
}
try {
echoinverse(5) ."\n";
} catch (Exception $e) {
echo'Excepción capturada: ',$e->getMessage(),"\n";
} finally {
echo"Primer finally.\n";
}
try {
echoinverse(0) ."\n";
} catch (Exception $e) {
echo'Excepción capturada: ',$e->getMessage(),"\n";
} finally {
echo"Segundo finally.\n";
}
// Continuar ejecución
echo'Hola Mundo\n';
?>El resultado del ejemplo sería:
0.2 Primer finally. Excepción capturada: División por cero. Segundo finally. Hola Mundo
Ejemplo #5 Excepciones anidadas
<?php
classMiExcepciónextendsException{ }
classPrueba{
public functionprobar() {
try {
try {
throw newMiExcepción('foo!');
} catch (MiExcepción $e) {
// relanzarla
throw$e;
}
} catch (Exception $e) {
var_dump($e->getMessage());
}
}
}
$foo= newPrueba;
$foo->probar();
?>El resultado del ejemplo sería:
string(4) "foo!"
(PHP 8 >= 8.1.0)
Fibers represent full-stack, interruptible functions. Fibers may be suspended from anywhere in the call-stack, pausing execution within the fiber until the fiber is resumed at a later time.
Fibers pause the entire execution stack, so the direct caller of the function does not need to change how it invokes the function.
Execution may be interrupted anywhere in the call stack usingFiber::suspend()(that is, the call toFiber::suspend()may be in a deeply nested function or not even exist at all).
Unlike stack-lessGenerators, eachFiberhas its own call stack, allowing them to be paused within deeply nested function calls. A function declaring an interruption point (that is, callingFiber::suspend()) need not change its return type, unlike a function usingyieldwhich must return aGeneratorinstance.
Fibers can be suspended in any function call, including those called from within the PHP VM, such as functions provided toarray_map()or methods called byforeachon anIteratorobject.
Once suspended, execution of the fiber may be resumed with any value usingFiber::resume()or by throwing an exception into the fiber usingFiber::throw(). The value is returned (or exception thrown) fromFiber::suspend().
Nota:Due to current limitations it is not possible to switch fibers in the destructor of an object.
Ejemplo #1 Basic usage
<?php
$fiber= newFiber(function ():void{
$value=Fiber::suspend('fiber');
echo"Value used to resume fiber: ",$value,PHP_EOL;
});
$value=$fiber->start();
echo"Value from fiber suspending: ",$value,PHP_EOL;
$fiber->resume('test');
?>El resultado del ejemplo sería:
Value from fiber suspending: fiber Value used to resume fiber: test
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Los generadores proporcionan un modo fácil de implementariteradoressimples sin la sobrecarga o complejidad de implementar una clase que implemente la interfazIterator.
Un generador permite escribir código que utiliceforeachpara iterar sobre un conjunto de datos sin que sea necesario cargar el array en memoria, lo que puede ocasionar que se exceda el límite de memoria, o requiera una cantidad considerable de tiempo de procesado para generarse. En su lugar, se puede escribir una función generadora, que es igual que unafunciónnormal, con la salvedad de que en vez de hacer un soloreturn, un generador puede invocaryieldtantas veces como necesite para proporcionar valores por los que iterar.
Un ejemplo simple de esto es reimplementar la funciónrange()como un generador. La función estándarrange()tiene que generar un array con cada uno de los valores y devolverlo, lo que puede resultar en arrays grandes: por ejemplo, llamarrange(0, 1000000)resultará en más de 100 MB de memoria utilizada.
Como alternativa, se puede implementar un generadorxrange(), que sólo necesitará memoria para crear un objetoIteratory controlar el estado actual del generador de manera interna, lo que no ocupa más de 1 kilobyte.
Ejemplo #1 Implementandorange()como generador
<?php
functionxrange($start,$limit,$step=1) {
if ($start<$limit) {
if ($step<=0) {
throw newLogicException('Step tiene que ser +ve');
}
for ($i=$start;$i<=$limit;$i+=$step) {
yield$i;
}
} else {
if ($step>=0) {
throw newLogicException('Step tiene que ser -ve');
}
for ($i=$start;$i>=$limit;$i+=$step) {
yield$i;
}
}
}
/*
* Obsereve que tanto range() como xrange() producen la misma
* salida a continuación.
*/
echo'Números impares de una cifra de range(): ';
foreach (range(1,9,2) as$number) {
echo"$number";
}
echo"\n";
echo'Números impares de una cifra de xrange(): ';
foreach (xrange(1,9,2) as$number) {
echo"$number";
}
?>El resultado del ejemplo sería:
Números impares de una cifra de range(): 1 3 5 7 9 Números impares de una cifra de xrange(): 1 3 5 7 9
Cuando una función generadora es invocada por primera vez, se devuelve un objeto de la clase internaGenerator. Este objeto implementa la interfazIteratorde la misma forma que lo haría un objeto iterador de solo avance, y proporciona métodos que pueden ser invocados para manipular el estado del generador, incluyendo el envío de valores hacia y la devolución de valores desde él.
Una función generadora es igual que una función normal, con la diferencia de que en vez de devolver un valor, un generador invocayieldtantas veces como necesita.
Cuando se llama a una función generadora, devuelve un objeto que puede ser iterado. Cuando se itera sobre ese objeto (por ejemplo, con un bucleforeach), PHP llamará a la función generadora cada vez que necesite un valor, y guardará el estado del generador cuando este provea un valor con yield para que ese estado pueda ser recuperado cuando el próximo valor sea requerido.
Cuando no hay más valores que se puedan proporcionar, la función generadora puede simplemente terminar, y el código desde el que se la llama continuará como si un array se hubiera quedado sin valores.
Nota:
Un generador no puede retornar un valor: hacerlo resultaría en un error de compilación. Unreturnvacío es válido en cuanto a sintaxis dentro de un generador y terminará el generador.
La clave de una función generadora es la palabra reservadayield. En su forma más simple, la sentencia yield es parecida a la sentencia return, excepto en que en vez de detener la ejecución de la función y devolver un valor, yield facilita el valor al bucle que itera sobre el generador y pausa la ejecución de la función generadora.
Ejemplo #1 Ejemplo sencillo de facilitar valores con yield
<?php
functiongen_one_to_three() {
for ($i=1;$i<=3;$i++) {
// Observe que $i es preservado entre yields
yield$i;
}
}
$generator=gen_one_to_three();
foreach ($generatoras$value) {
echo"$value\n";
}
?>El resultado del ejemplo sería:
1 2 3
Nota:
Internamente, las claves enteras secuenciales serán asociadas con los valores sobre los que se usa yield, como un array no asociativo.
Si se utiliza yield en el contexto de una expresión (por ejemplo, en el lado derecho de una asignación), se debe poner la sentencia yield entre paréntesis en PHP 5. Por ejemplo, esto es válido:
$data = (yield $value);Pero esto no lo es, y resultará en un error de análisis en PHP 5:
$data = yield $value;Las restricciones parentéticas no se aplican en PHP 7.
Esta sintaxis podría usarse junto con el métodoGenerator::send().
PHP soporta arrays asociativos, y los generadores no son menos. Además de facilitar valores simples, como se muestra arriba, también se puede facilitar una clave al mismo tiempo.
La sintaxis para facilitar un par clave-valor es muy similar a la utilizada para definir un array asociativo, como se muestra a continuación.
Ejemplo #2 Facilitar un par clave-valor
<?php
/*
* La entrada son campos separados por punto y coma, con el primer
* campo siendo la ID utilizada como clave.
*/
$input= <<<'EOF'
1;PHP;Likes dollar signs
2;Python;Likes whitespace
3;Ruby;Likes blocks
EOF;
functioninput_parser($input) {
foreach (explode("\n",$input) as$line) {
$fields=explode(';',$line);
$id=array_shift($fields);
yield$id=>$fields;
}
}
foreach (input_parser($input) as$id=>$fields) {
echo"$id:\n";
echo"$fields[0]\n";
echo"$fields[1]\n";
}
?>El resultado del ejemplo sería:
1:
PHP
Likes dollar signs
2:
Python
Likes whitespace
3:
Ruby
Likes blocks
Como en el ejemplo anterior, facilitar un par clave-valor en contexto de expresión requiere que la sentencia yield sea puesta entre paréntesis:
$data = (yield $key => $value);Yield puede ser invocado sin argumentos para facilitar un valornullcon una clave automática.
Ejemplo #3 Yieldingnulls
<?php
functiongen_three_nulls() {
foreach (range(1,3) as$i) {
yield;
}
}
var_dump(iterator_to_array(gen_three_nulls()));
?>El resultado del ejemplo sería:
array(3) {
[0]=>
NULL
[1]=>
NULL
[2]=>
NULL
}
Las funciones generadoras son capaces de facilitar valores por referencia igual que lo hacen por valor. Esto se hace de la misma forma quedevolviendo referencias desde funciones: poniendo un ampersand (signo &) delante del nombre de la función.
Ejemplo #4 Facilitar valores por referencia
<?php
function &gen_reference() {
$value=3;
while ($value>0) {
yield$value;
}
}
/*
* Observe que es posible cambiar $number desde dentro del bucle, y
* dado que el generador está facilitando referencias, $value
* dentro de gen_reference() cambia.
*/
foreach (gen_reference() as &$number) {
echo (--$number).'... ';
}
?>El resultado del ejemplo sería:
2... 1... 0...
En PHP 7, la delegación de generadores permite producir valores desde otro generador, objetoTraversable, oarraymediante la palabra reservadayield from. El generador externo producirá entonces todos los valores desde el generador interno, object, o array hasta que este ya no sea válido, después de lo cual la ejecuión continuará en el generador externo.
Si un generador se emplea conyield from, la expresiónyield fromtambién devolverá cualquier valor devuelto por el generador interno.
yield fromno reinicia las claves. Preserva las claves devueltas por el objetoTraversableoarray. Por tanto, algunos valores podrían compartir una clave en común con otroyieldoyield from, los cuales, en el momento de la inserción en el array, sobrescribirán los valores antiguos con esa clave.
Un caso común donde esto importa es cuandoiterator_to_array()devuelve un array con claves por defecto, conduciendo a posibles resultados inesperados.iterator_to_array()tiene un segundo parámetro,use_keys, que puede ser establecido afalsepara recoger todos los valores mientras ignora las claves devueltas por elGenerator.
Ejemplo #5yield fromconiterator_to_array()
<?php
functionfrom() {
yield1;// clave 0
yield2;// clave 1
yield3;// clave 2
}
functiongen() {
yield0;// clave 0
yield fromfrom();// claves 0-2
yield4;// clave 1
}
// pasar false como segundo parámetro para obtener un array [0, 1, 2, 3, 4]
var_dump(iterator_to_array(gen()));
?>El resultado del ejemplo sería:
array(3) {
[0]=>
int(1)
[1]=>
int(4)
[2]=>
int(3)
}
Ejemplo #6 Uso básico deyield from
<?php
functioncontar_hasta_diez() {
yield1;
yield2;
yield from [3,4];
yield from newArrayIterator([5,6]);
yield fromsiete_ocho();
yield9;
yield10;
}
functionsiete_ocho() {
yield7;
yield fromocho();
}
functionocho() {
yield8;
}
foreach (contar_hasta_diez() as$num) {
echo"$num";
}
?>El resultado del ejemplo sería:
1 2 3 4 5 6 7 8 9 10
Ejemplo #7yield fromy valores devueltos
<?php
functioncontar_hasta_diez() {
yield1;
yield2;
yield from [3,4];
yield from newArrayIterator([5,6]);
yield fromsiete_ocho();
return yield fromnueve_diez();
}
functionsiete_ocho() {
yield7;
yield fromocho();
}
functionocho() {
yield8;
}
functionnueve_diez() {
yield9;
return10;
}
$gen=contar_hasta_diez();
foreach ($genas$num) {
echo"$num";
}
echo$gen->getReturn();
?>El resultado del ejemplo sería:
1 2 3 4 5 6 7 8 9 10
La principal ventaja de los generadores es su simplicadad. Se ha de escribir mucho menos código repetitivo en comparación con el necesario para implementar una claseIterator, y el código es generalmente mucho más legible. Por ejemplo, la siguiente función y clase son equivalentes:
<?php
functiongetLinesFromFile($fileName) {
if (!$fileHandle=fopen($fileName,'r')) {
return;
}
while (false!==$line=fgets($fileHandle)) {
yield$line;
}
fclose($fileHandle);
}
// Contra...
classLineIteratorimplementsIterator{
protected$fileHandle;
protected$line;
protected$i;
public function__construct($fileName) {
if (!$this->fileHandle=fopen($fileName,'r')) {
throw newRuntimeException('Couldn\'t open file "'.$fileName.'"');
}
}
public functionrewind() {
fseek($this->fileHandle,0);
$this->line=fgets($this->fileHandle);
$this->i=0;
}
public functionvalid() {
returnfalse!==$this->line;
}
public functioncurrent() {
return$this->line;
}
public functionkey() {
return$this->i;
}
public functionnext() {
if (false!==$this->line) {
$this->line=fgets($this->fileHandle);
$this->i++;
}
}
public function__destruct() {
fclose($this->fileHandle);
}
}
?>La flexibilidad, sin embargo, tiene un coste: los generadores son iteradores unidireccionales, ya que no pueden ser rebobinados una vez la iteración ha empezado. Esto también significa que se puede iterar sobre el mismo generador varias veces: el generador necesitará ser reconstruido llamando a la función generadora de nuevo.
(PHP 8)
Attributes offer the ability to add structured, machine-readable metadata information on declarations in code: Classes, methods, functions, parameters, properties and class constants can be the target of an attribute. The metadata defined by attributes can then be inspected at runtime using theReflection APIs. Attributes could therefore be thought of as a configuration language embedded directly into code.
With attributes the generic implementation of a feature and its concrete use in an application can be decoupled. In a way it is comparable to interfaces and their implementations. But where interfaces and implementations are about code, attributes are about annotating extra information and configuration. Interfaces can be implemented by classes, yet attributes can also be declared on methods, functions, parameters, properties and class constants. As such they are more flexible than interfaces.
A simple example of attribute usage is to convert an interface that has optional methods to use attributes. Let's assume anActionHandlerinterface representing an operation in an application, where some implementations of an action handler require setup and others do not. Instead of requiring all classes that implementActionHandlerto implement a methodsetUp(), an attribute can be used. One benefit of this approach is that we can use the attribute several times.
Ejemplo #1 Implementing optional methods of an interface with Attributes
<?php
interfaceActionHandler
{
public functionexecute();
}
#[Attribute]
classSetUp{}
classCopyFileimplementsActionHandler
{
publicstring $fileName;
publicstring $targetDirectory;
#[SetUp]
public functionfileExists()
{
if (!file_exists($this->fileName)) {
throw newRuntimeException("File does not exist");
}
}
#[SetUp]
public functiontargetDirectoryExists()
{
if (!file_exists($this->targetDirectory)) {
mkdir($this->targetDirectory);
} elseif (!is_dir($this->targetDirectory)) {
throw newRuntimeException("Target directory$this->targetDirectoryis not a directory");
}
}
public functionexecute()
{
copy($this->fileName,$this->targetDirectory.'/'.basename($this->fileName));
}
}
functionexecuteAction(ActionHandler $actionHandler)
{
$reflection= newReflectionObject($actionHandler);
foreach ($reflection->getMethods() as$method) {
$attributes=$method->getAttributes(SetUp::class);
if (count($attributes) >0) {
$methodName=$method->getName();
$actionHandler->$methodName();
}
}
$actionHandler->execute();
}
$copyAction= newCopyFile();
$copyAction->fileName="/tmp/foo.jpg";
$copyAction->targetDirectory="/home/user";
executeAction($copyAction);There are several parts to the attributes syntax. First, an attribute declaration is always enclosed with a starting#[and a corresponding ending]. Inside, one or many attributes are listed, separated by comma. The attribute name is an unqualified, qualified or fully-qualified name as described inUsing Namespaces Basics. Arguments to the attribute are optional, but are enclosed in the usual parenthesis(). Arguments to attributes can only be literal values or constant expressions. Both positional and named arguments syntax can be used.
Attribute names and their arguments are resolved to a class and the arguments are passed to its constructor, when an instance of the attribute is requested through the Reflection API. As such a class should be introduced for each attribute.
Ejemplo #1 Attribute Syntax
<?php
// a.php
namespaceMyExample;
useAttribute;
#[Attribute]
classMyAttribute
{
constVALUE='value';
private$value;
public function__construct($value=null)
{
$this->value=$value;
}
}
// b.php
namespaceAnother;
useMyExample\MyAttribute;
#[MyAttribute]
#[\MyExample\MyAttribute]
#[MyAttribute(1234)]
#[MyAttribute(value: 1234)]
#[MyAttribute(MyAttribute::VALUE)]
#[MyAttribute(array("key" => "value"))]
#[MyAttribute(100 + 200)]
classThing
{
}
#[MyAttribute(1234), MyAttribute(5678)]
classAnotherThing
{
}To access attributes from classes, methods, functions, parameters, properties and class constants, the Reflection API provides the methodgetAttributes()on each of the corresponding Reflection objects. This method returns an array ofReflectionAttributeinstances that can be queried for attribute name, arguments and to instantiate an instance of the represented attribute.
This separation of reflected attribute representation from actual instance increases control of the programmer to handle errors regarding missing attribute classes, mistyped or missing arguments. Only after callingReflectionAttribute::newInstance(), objects of the attribute class are instantiated and the correct matching of arguments is validated, not earlier.
Ejemplo #1 Reading Attributes using Reflection API
<?php
#[Attribute]
classMyAttribute
{
public$value;
public function__construct($value)
{
$this->value=$value;
}
}
#[MyAttribute(value: 1234)]
classThing
{
}
functiondumpAttributeData($reflection) {
$attributes=$reflection->getAttributes();
foreach ($attributesas$attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}
dumpAttributeData(newReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
["value"]=>
int(1234)
}
object(MyAttribute)#3 (1) {
["value"]=>
int(1234)
}
*/Instead of iterating all attributes on the reflection instance, only those of a particular attribute class can be retrieved by passing the searched attribute class name as argument.
Ejemplo #2 Reading Specific Attributes using Reflection API
<?php
functiondumpMyAttributeData($reflection) {
$attributes=$reflection->getAttributes(MyAttribute::class);
foreach ($attributesas$attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}
dumpMyAttributeData(newReflectionClass(Thing::class));While not strictly required it is recommended to create an actual class for every attribute. In the most simple case only an empty class is needed with the#[Attribute]attribute declared that can be imported from the global namespace with a use statement.
Ejemplo #1 Simple Attribute Class
<?php
namespaceExample;
useAttribute;
#[Attribute]
classMyAttribute
{
}To restrict the type of declaration an attribute can be assigned to, a bitmask can be passed as the first argument to the#[Attribute]declaration.
Ejemplo #2 Using target specification to restrict where attributes can be used
<?php
namespaceExample;
useAttribute;
#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
classMyAttribute
{
}DeclaringMyAttributeon another type will now throw an exception during the call toReflectionAttribute::newInstance()
The following targets can be specified:
Attribute::TARGET_CLASSAttribute::TARGET_FUNCTIONAttribute::TARGET_METHODAttribute::TARGET_PROPERTYAttribute::TARGET_CLASS_CONSTANTAttribute::TARGET_PARAMETERAttribute::TARGET_ALLBy default an attribute can only be used once per declaration. If the attribute should be repeatable on declarations it must be specified as part of the bitmask to the#[Attribute]declaration.
Ejemplo #3 Using IS_REPEATABLE to allow attribute on a declaration multiple times
<?php
namespaceExample;
useAttribute;
#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
classMyAttribute
{
}Las Referencias en PHP son medios de acceder al mismo contenido de una variable mediante diferentes nombres. No son como los punteros de C; por ejemplo, no se puede realizar aritmética de punteros con ellas, realmente no son direcciones de memoria, etc. Véase¿Qué NO son las Referencias?para más información. Las referencias son alias de la tabla de símbolos. Observe que en PHP el nombre de la variable y el contenido de la variable son cosas diferentes, por lo que el mismo contenido puede tener diferentes nombres. La analogía más próxima es con los archivos y los nombres de archivos de Unix - los nombres de variables son entradas de directorio, mientras que el contenido de las variables es el archivo en sí. Las referencias se pueden vincular a enlaces duros en sistemas de archivos Unix.
Hay tres operaciones básicas que se realizan usando referencias:asignar por referencia,pasar por referencia, ydevolver por referencia. En esta sección se dará una introducción a estas operaciones, con enlaces para una lectura complementaria.
En la primera de estas operaciones, las referencias de PHP permiten hacer que dos variables hagan referencia al mismo contenido. Es decir, cuando se hace:
<?php
$a=&$b;
?>Nota:
$ay$baquí son completamente iguales.$ano está apuntando a$bo viceversa.$ay$bestán apuntando al mismo lugar.
Nota:
Si se asigna, pasa, o devuelve una variable no definida por referencia, la variable se creará.
Ejemplo #1 Usar referencias con variables no definidas
<?php
functionfoo(&$var) { }
foo($a);// $a es "creada" y asignada a null
$b= array();
foo($b['b']);
var_dump(array_key_exists('b',$b));// bool(true)
$c= newStdClass;
foo($c->d);
var_dump(property_exists($c,'d'));// bool(true)
?>
Se puede usar la misma sintaxis con funciones que devuelven referencias:
<?php
$foo=&find_var($bar);
?>=&en este contexto es obsoleto y produce un mensajeE_DEPRECATEDen PHP 5.3 y posteriores, y un mensajeE_STRICTen versiones anteriores. A partir de PHP 7.0 es sintácticamente inválido. (Técnicamente, la diferencia es que, en PHP 5, las variables de objetos, como los recursos, son meros punteros a la información del objeto actual, por lo que estas referencias a objetos no son "referencias" en el mismo sentido usado antes (alias). Para más información, véaseObjetos y referencias.)Si se asigna una referencia a una varible declaradaglobaldentro de una función, la referencia será visible sólo dentro de la función. Se puede evitar esto usando la matriz$GLOBALS.
Ejemplo #2 Refenciar variables globales dentro de funciones
<?php
$var1="Variable de ejemplo";
$var2="";
functionreferencias_globales($usar_globals)
{
global$var1,$var2;
if (!$usar_globals) {
$var2=&$var1;// visible sólo dentro de la función
} else {
$GLOBALS["var2"] =&$var1;// visible también en el contexto global
}
}
referencias_globales(false);
echo"var2 está establecida a '$var2'\n";// var2 está establecida a ''
referencias_globales(true);
echo"var2 está establecida a '$var2'\n";// var2 está establecida a 'Variable de ejemplo'
?>global $var;como simplificación de$var =& $GLOBALS['var'];. De este modo, al asignar otra referencia a$varsólo cambia la referencia de la variable local.Nota:
Si se asigna un valor a una variable con referencias en una sentenciaforeach, también se modifican las referencias.
Ejemplo #3 Referencias y la sentencia foreach
<?php
$ref=0;
$fila=&$ref;
foreach (array(1,2,3) as$fila) {
// hacer algo
}
echo$ref;// 3 - último elemento de la matriz iterada
?>
Mientras que no sea estrictamente una asignación por referencia, las expresiones creadas con el constructor de lenguajearray()también pueden comportarse como tales prefijando&al elemento del array a añadir. Ejemplo:
<?php
$a=1;
$b= array(2,3);
$arr= array(&$a, &$b[0], &$b[1]);
$arr[0]++;$arr[1]++;$arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>Observe, sin embargo, que las referencias dentro de arrays son potencialmente peligrosas. Realizar una asignación normal (no por referencia) con una referencia en el lado derecho no convierte el lado izquierdo en una referencia, pero las referencias dentro de arrays son conservadas en estas asignaciones normales. Esto también se aplica a las llamadas a funciones donde el array es pasado por valor. Ejemplo:
<?php
/* Asignación de variables escalares */
$a=1;
$b=&$a;
$c=$b;
$c=7;//$c no es una referencia; no cambia $a o $b
/* Asignación de variables de array */
$arr= array(1);
$a=&$arr[0];// $a y $arr[0] son el mismo conjunto de referencias
$arr2=$arr;// ¡no es una asignación por referencia!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* ¡El contenido de $arr se cambia incluso si no es una referencia! */
?>Lo segundo que hacen las referencias es pasar variables por referencia. Esto se lleva a cabo haciendo que una variable local en una función y una variable en el ámbito de la llamada referencien al mismo contenido. Ejemplo:
<?php
functionfoo(&$var)
{
$var++;
}
$a=5;
foo($a);
?>Lo tercero que hacen las referncias esdevolver por referencia.
Como se dijo antes, las referencias no son punteros. Es decir, la siguiente construcción no hará lo que se esperaba:
<?php
functionfoo(&$var)
{
$var=&$GLOBALS["baz"];
}
foo($bar);
?>Lo que sucede es que$varenfooserá ligada con$baren la llamada, pero entonces será religada con$GLOBALS["baz"]. No hay forma de ligar$baren el ámbito de la llamada a otra cosa usando el mecanismo de referencia, ya que$barno está disponible en la funciónfoo(está representada por$var, pero$varsólo tiene el contenido de la variable y no la vinculación nombre-a-valor en la tabla de símbolos de llamada). Se puede usardevolver referenciaspara referencias variables seleccionadas por la función.
Se puede pasar una variable por referencia a una función y así hacer que la función pueda modificar la variable. La sintaxis es la siguiente:
<?php
functionfoo(&$var)
{
$var++;
}
$a=5;
foo($a);
// $a es 6 aquí
?>Nota:No existe ningún signo de referencia en una llamada a una función - sólo en la definición de la función. Las definiciones de funciones por sí solas son suficientes para pasar correctamente el argumento por referencia. A partir de PHP 5.3.0, se obtendrá una advertencia diciendo que "call-time pass-by-reference" (pasar por referencia en tiempo de llamada) está obsoleto cuando se use & en
foo(&$a);. A partir de PHP 5.4.0, el paso por referencia en tiempo de llamada ha sido eliminado, por lo que su uso emitirá un error fatal.
Se puede pasar por referencia lo siguiente:
foo($a)Referencias devueltas desde funciones, esto es:
<?php
functionfoo(&$var)
{
$var++;
}
function &bar()
{
$a=5;
return$a;
}
foo(bar());
?>Ninguna otra expresión debería pasarse por referencia, ya que el resultado no está definido. Por ejemplo, los siguientes ejemplos de pasar por referencia no son válidos:
<?php
functionfoo(&$var)
{
$var++;
}
functionbar()// Observe que falta el &
{
$a=5;
return$a;
}
foo(bar());// Produce un error fatal a partir de PHP 5.0.5,un aviso de estándar estricto
// a partir de PHP 5.1.1, y un aviso a partir de PHP 7.0.0
foo($a=5);// Expresión, no una variable
foo(5);// Produce un error fatal
classFoobar
{
}
foo(newFoobar())// Produce un aviso a partir de PHP 7.0.7
// Observación: Solo las variables deben pasarse por referencia
?>Devolver por referencia es útil cuando se quiere usar una función para encontrar a qué variable debería estar vinculada una referencia.Nouse devolver por referencia para aumentar el rendimiento. El motor optimizará automáticamente esto por sí mismo. Hay que devolver referencias sólo cuando se tenga una razón técnicamente válida para hacerlo. Para devolver referencias use esta sintaxis:
<?php
classfoo{
public$valor=42;
public function &obtenerValor() {
return$this->valor;
}
}
$obj= newfoo;
$miValor= &$obj->obtenerValor();// $miValor es una referencia a $obj->valor, que es 42.
$obj->valor=2;
echo$miValor;// imprime el nuevo valor de $obj->valor, esto es, 2.
?>Nota:A diferencia de pasar un parámetro, aquí se tiene que usar
&en ambos lugares - para indicar que se quiere devolver por referencia, no una copia, y para indicar que la vinculación por referencia, en vez de la asignación normal, debería ser hecha para$miValor.
Nota:Si se intenta devolver una referencia desde una función con la sintaxis:
return ($this->valor);,nofuncionará ya que se está intentando devolver el resultado de unaexpresión, y no de una variable, por referencia. Sólo se puede devolver variables por referencia desde una función - nada más. Desde PHP 5.1.0, se emite un errorE_NOTICEsi el código intenta devolver una expresión dinámica o un resultado del operadornew.
Para usar la referencia retornada, se debe usar la asignación por referencia:
<?php
function &collector() {
static$collection= array();
return$collection;
}
$collection= &collector();
$collection[] ='foo';
?><?php
function &collector() {
static$collection= array();
return$collection;
}
array_push(collector(),'foo');
?>Nota:Observe que
array_push(&collector(), 'foo');nofuncionará, resultará en un error fatal.
Cuando se destruye una referencia, se rompe el vínculo entre el nombre de la variable y el contenido de la variable. Esto no significa que el contenido de la variable sea destruida. Por ejemplo:
<?php
$a=1;
$b=&$a;
unset($a);
?>De nuevo, podría ser útil pensar en esto como análogo a una llamada aunlinkde Unix.
Muchas construcciones sintácticas de PHP están implementadas mediante el mecanismo de referencia, por lo que todo lo mencionado aquí sobre la vinculación de referencias también se aplica a estas construcciones. Algunas construcciones, como pasar y devolver por referencia, han sido mencionadas antes. Otras construcciones que usan referencias son:
Cuando se declara una variable comoglobal $var, de hecho se está creando una referencia a una variable global. Es decir, esto es lo mismo que:
<?php
$var=&$GLOBALS["var"];
?>Esto también significa que al destruir$varno se destruirá la variable global.
$thisEn un método de un objeto,$thises siempre una referencia al objeto llamado.
PHP proporciona una gran cantidad de variables predefinidas para todos los scripts. Las variables representan de todo, desdevariables externashasta variables de entorno incorporadas, desde los últimos mensajes de error hasta los últimos encabezados recuperados.
Superglobals—Superglobals son variables internas que están disponibles siempre en todos los ámbitos
Algunas variables predefinidas en PHP son "superglobales", lo que significa que están disponibles en todos los ámbitos a lo largo del script. No es necesario emplearglobal $variable;para acceder a ellas dentro de las funciones o métodos.
Las variables superglobals son:
Nota:Disponibilidad de variables
Por defecto, todas las superglobals están disponibles pero hay directivas que afectan a su disponibilidad. Para más información, véase la documentacion devariables_order.
Nota:Variables variables
Las variables superglobals no pueden ser usadas comovariables variablesdentro de funciones o métodos de clase.
(PHP 4, PHP 5, PHP 7, PHP 8)
$GLOBALS—Hace referencia a todas las variables disponibles en el ámbito global
Es unarrayasociativo que contiene las referencias a todas la variables que están definidas en el ámbito global del script. Los nombres de las variables son las claves del array.
Ejemplo #1 Ejemplo de$GLOBALS
<?php
functiontest() {
$foo="variable local";
echo'$foo en el ámbito global: '.$GLOBALS["foo"] ."\n";
echo'$foo en el ámbito simple: '.$foo."\n";
}
$foo="Contenido de ejemplo";
test();
?>El resultado del ejemplo sería algo similar a:
$foo en el ámbito global: Contenido de ejemplo $foo en el ámbito simple: variable local
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
Nota:Disponibilidad de las variables
A diferencia de todas las otrassuperglobals,$GLOBALSha estado esencialmente siempre disponible en PHP.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_SERVER--$HTTP_SERVER_VARS [eliminado]—Información del entorno del servidor y de ejecución
$_SERVERes un array que contiene información, tales como cabeceras, rutas y ubicaciones de script. Las entradas de este array son creadas por el servidor web. No hay garantía que cada servidor web proporcione alguna de estas entradas, existen servidores que pueden omitir algunas o proporcionar otras no recogidas aquí. Un gran número de estas variables se encuentran recogidas en» especificación CGI 1.1, así que al menos debe esperar encontrar estas entradas.
Nota:Antes de PHP 5.4.0,$HTTP_SERVER_VARScontenía la misma información inicial, aunque no era unasuperglobal. (Observe que$HTTP_SERVER_VARSy$_SERVEReran variables diferentes, por lo que PHP las trata de forma distinta).
Puede encontrar o no los siguientes elementos en$_SERVER. Tenga en cuenta que si ejecuta PHP desdelínea de comandopocos o ninguno de los siguientes elementos estarán disponibles (o tendrán algún significado).
CGI/1.1'.Nota:Bajo Apache 2, se debe establecer
UseCanonicalName = OnyServerName. De lo contrario, este valor refleja el nombre del host proporcionado por el cliente, el cual se puede burlar. No es seguro depender de este valor en contextos que necesiten seguridad.
HTTP/1.0'.GET', 'HEAD', 'POST', 'PUT'.Nota:
El script de PHP se considera terminado después de enviar las cabeceras (es decir después de producir cualquier resultado sin emplear buffers para el resultado) si el método de la petición empleado era
HEAD.
Accept:de la petición actual, si existe.Accept-Charset:de la petición actual, si existe. Por ejemplo: 'iso-8859-1,*,utf-8'.Accept-Encoding:de la petición actual, si existe. Por ejemplo: 'gzip'.Accept-Language:de la petición actual, si existe. Por ejemplo: 'en'.Connection:de la petición actual, si existe. Por ejemplo: 'Keep-Alive'.Host:de la petición actual, si existe.User-Agent:de la petición actual, si existe. Consiste en una cadena que indica el agente de usuario empleado para acceder a la pagina. Un ejemplo típico es:Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Entre otras opciones, puede emplear dicho valor conget_browser()para personalizar el resultado de la salida de la página en función de las capacidades del agente de usuario empleado.Nota:Tenga en cuenta que si se emplea ISAPI con IIS el valor será
offsi la petición no se ha realizado a través del protocolo HTTPS.
Nota:Su servidor web debe estar configurado para crear esta variable. Por ejemplo en Apache necesita que exista
HostnameLookups Ondentro dehttpd.conf. Consulte tambiengethostbyaddr().
La ruta del script ejecutándose actualmente en forma absoluta.
Nota:
Si un script se ejecuta mediante CLI como ruta relativa, como por ejemplofile.phpo../file.php, entonces$_SERVER['SCRIPT_FILENAME']contendrá la ruta relativa especificada por el usuario.
80'; el empleo de SSL, por ejemplo, cambiará dicho valor al valor definido para el puerto HTTP seguro.Nota:Bajo Apache 2, se debe establecer
UseCanonicalName = On, así comoUseCanonicalPhysicalPort = Onpara poder obtener el puerto físico (real), de otro modo, este valor podría ser burlado y podría o no devolver el valor del puerto físico. No es seguro confiar en este valor en contextos que requieran seguridad.
Nota:A partir de PHP 4.3.2,PATH_TRANSLATEDno está definida de forma implícita en elSAPIde Apache 2, en comparación a la situación de Apache 1, donde era necesario establecer el mismo valor que la variable del servidorSCRIPT_FILENAMEcuando no era proporcionada por Apache. Este cambio ha sido realizado para cumplir la especificaciónCGIdondePATH_TRANSLATEDsólo debe existir siPATH_INFOesta definida.Los usuarios de Apache 2 pueden emplear
AcceptPathInfo = Ondentro dehttpd.confpara definirPATH_INFO.
/index.html'./some/stuff.| Versión | Descripción |
|---|---|
| 5.4.0 | $HTTP_SERVER_VARSya no está disponible debido a la eliminación de arrays grandes de registro. |
| 5.3.0 | La directivaregister_long_arrays, la cual hacía que estuviera disponible$HTTP_SERVER_VARSestá obsoleta. |
Ejemplo #1Ejemplo de $_SERVER
<?php
echo$_SERVER['SERVER_NAME'];
?>El resultado del ejemplo sería algo similar a:
www.example.com
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_GET--$HTTP_GET_VARS [obsoleta]—Variables HTTP GET
Un array asociativo de variables pasado al script actual vía parámetros URL (también conocida como cadena de consulta). Tenga en cuenta que el array no solo se rellena para las solicitudes GET, sino para todas las solicitudes con una cadena de consulta.
$HTTP_GET_VARScontiene la misma información, pero no es unasuperglobal. (Note que$HTTP_GET_VARSy$_GETson diferentes variables y que PHP los usa de forma diferente)
Ejemplo #1 Ejemplo de$_GET
<?php
echo'¡Hola '.htmlspecialchars($_GET["nombre"]) .'!';
?>Asumiendo que el usuario introdujo http://example.com/?nombre=Hannes
El resultado del ejemplo sería algo similar a:
¡Hola Hannes!
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
Nota:
Las variables GET son pasadas víaurldecode().
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_POST--$HTTP_POST_VARS [obsoleta]—Variables POST de HTTP
Un array asociativo de variables pasadas al script actual a través del método POST de HTTP cuando se empleaapplication/x-www-form-urlencodedomultipart/form-datacomo Content-Type de HTTP en la petición.
$HTTP_POST_VARScontiene la misma información inicial, aunque no es unasuperglobal. (Observe que$HTTP_POST_VARSy$_POSTson variables diferentes, por lo que PHP las trata de forma distinta).
Ejemplo #1 Ejemplo de$_POST
<?php
echo'¡Hola '.htmlspecialchars($_POST["nombre"]) .'!';
?>Asumiendo que el usuario envió por el método POST nombre=Juan
El resultado del ejemplo sería algo similar a:
¡Hola Juan!
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_FILES--$HTTP_POST_FILES [obsoleta]—Variables de subida de ficheros HTTP
Unarrayasociativo de elementos subidos al script en curso a través del método POST. La estructura de este array se resume en la secciónSubidas con el método POST.
$HTTP_POST_FILEScontiene la misma información inicial, pero no essuperglobal. (Observe que$HTTP_POST_FILESy$_FILESson variables diferentes y que PHP las trata como tal).
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_REQUEST—Variables HTTP Request
| Versión | Descripción |
|---|---|
| 5.3.0 | Se introdujorequest_order. Esta directiva afecta al contenido de$_REQUEST. |
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
Nota:
Cuando se ejecuta en lalínea de comandos,nose incluirán las entradasargvyargc; ya que están presentes en elarray$_SERVER
Nota:
Las variables en$_REQUESTse proporcionan al script a través de los mecanismos de entrada GET, POST, y COOKIE y por lo tanto pueden ser manipulados por el usuario remoto y no debe confiar en el contenido. La presencia y el orden de las variables listadas en este array se definen según la directiva de configuración PHPvariables_order.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_SESSION--$HTTP_SESSION_VARS [obsoleta]—Variables de sesión
Es un array asociativo que contiene variables de sesión disponibles para el script actual. Ver la documentación deFunciones de sesiónpara más información sobre su uso.
$HTTP_SESSION_VARScontiene la misma información inicial pero no es unasuperglobal. (Nótese que$HTTP_SESSION_VARSy$_SESSIONson diferentes variables y PHP las trata de forma distinta)
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
$_ENV--$HTTP_ENV_VARS [obsoleta]—Variables de entorno
Una variable tipoarrayasociativo de variables pasadas al script actual a través del método del entorno.
Estas variables son importadas en el espacio de nombres global de PHP desde el entorno bajo el que está siendo ejecutado el intérprete PHP. Muchas son entregadas por el intérprete de comandos bajo el que PHP está corriendo y diferentes sistemas suelen tener diferentes tipos de intérpretes de comandos, una lista definitiva es imposible. Por favor consulte la documentación de su intérprete de comandos para una lista de las variables de entorno que se definen.
Otras variables de entorno incluyen las variables CGI, colocadas allí independientemente de que PHP esté siendo ejecutado como módulo del servidor o procesador CGI.
$HTTP_ENV_VARScontiene la misma información inicial, pero no es unasuperglobal. (Note que$HTTP_ENV_VARSy$_ENVson variables diferentes y que PHP las trata como tal)
Ejemplo #1 Ejemplo de$_ENV
<?php
echo'¡Mi nombre de usuario es '.$_ENV["USER"] .'!';
?>Asumiendo que "bjori" ejecuta este script
El resultado del ejemplo sería algo similar a:
¡Mi nombre de usuario es bjori!
Nota:
Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.
(PHP 4, PHP 5, PHP 7)
$php_errormsg—El mensaje de error anterior
Esta característica ha sido declaradaOBSOLETAa partir de PHP 7.2.0. Su uso está totalmente desaconsejado.
Utiliceerror_get_last()en su lugar.
$php_errormsges una variable que contiene el texto del último mensaje de error generado por PHP. Esta variable solo estará disponible dentro del ámbito donde ocurrió el error, y solamente funcionará si la opción de configuracióntrack_errorsestá activada (por defecto está desactivada).
Si está definido un manejador de errores (set_error_handler()),$php_errormsgestará establecido solamente si el manejador de errores devuelvefalse
Ejemplo #1 Ejemplo de$php_errormsg
<?php
@strpos();
echo$php_errormsg;
?>El resultado del ejemplo sería algo similar a:
Wrong parameter count for strpos()
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
$http_response_header—Encabezados de respuesta HTTP
Elarray$http_response_headeres similar a la functiónget_headers(). Cuando se hace uso deHTTP wrapper,$http_response_headerserá poblado con los encabezados de respuesta HTTP.$http_response_headerserá creada en elámbito local.
Ejemplo #1 Ejemplo de$http_response_header
<?php
functionget_contents() {
file_get_contents("http://example.com");
var_dump($http_response_header);
}
get_contents();
var_dump($http_response_header);
?>El resultado del ejemplo sería algo similar a:
array(9) {
[0]=>
string(15) "HTTP/1.1 200 OK"
[1]=>
string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
[2]=>
string(29) "Server: Apache/2.2.3 (CentOS)"
[3]=>
string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
[4]=>
string(27) "ETag: "280100-1b6-80bfd280""
[5]=>
string(20) "Accept-Ranges: bytes"
[6]=>
string(19) "Content-Length: 438"
[7]=>
string(17) "Connection: close"
[8]=>
string(38) "Content-Type: text/html; charset=UTF-8"
}
NULL
(PHP 4, PHP 5, PHP 7, PHP 8)
$argc—El número de argumentos pasados a un script
Contiene el número de argumentos pasados al script actual cuando se ejecuta desde lalínea de comandos.
Nota:El nombre del script es pasado siempre como argumento del script, por lo tanto, el valor mínimo de$argces
1.
Nota:Esta variable sólo está disponible cuandoregister_argc_argvestá activado.
Ejemplo #1 Ejemplo de$argc
<?php
var_dump($argc);
?>Cuando se ejecuta el ejemplo con: php script.php arg1 arg2 arg3
El resultado del ejemplo sería algo similar a:
int(4)
Nota:
Esto también está disponible como$_SERVER['argc'].
(PHP 4, PHP 5, PHP 7, PHP 8)
$argv—Array de argumentos pasados a un script
Contiene unarrayde todos los argumentos pasados a un script cuando se ejecuta desde lalínea de comandos.
Nota:El primer argumento$argv[0]siempre es el nombre del fichero que fue usado para ejecutar el script.
Nota:Esta variable no está disponible siregister_argc_argvestá deshabilitado.
Ejemplo #1 Ejemplo de$argv
<?php
var_dump($argv);
?>Cuando se ejecuta el ejemplo con: php script.php arg1 arg2 arg3
El resultado del ejemplo sería algo similar a:
array(4) {
[0]=>
string(10) "script.php"
[1]=>
string(4) "arg1"
[2]=>
string(4) "arg2"
[3]=>
string(4) "arg3"
}
Nota:
Esto también está disponible como$_SERVER['argv'].
Véanse también lasExcepciones de la SPL
(PHP 5, PHP 7, PHP 8)
Exceptiones la clase base para todas las excepciones en PHP 5, y la clase base para todas las excepciones de usuario en PHP 7.
Antes de PHP 7,Exceptionno implementa la interfazThrowable.
El mensaje de la excepción
El código de la excepción
El nombre del fichero donde se originó la excepción
La línea donde se originó la excepción
(PHP 5, PHP 7, PHP 8)
Exception::__construct—Constructor de la excepción
Construye el objeto Exception.
messageMensaje de la excepción a lanzar.
codeEl código de la excepción.
previousLa excepción previa utilizada por la serie de excepciones.
Nota:Llamar al constructor de la clase Exception de una subclase ignora los argumentos por omisión, si las propiedades $code y $message ya están establecidas.
| Versión | Descripción |
|---|---|
| 7.0.0 | El parámetropreviousahora es del tipoThrowable. |
| 5.3.0 | Se añadió el parámetroprevious. |
Nota:
messageNOes seguro binariamente.
(PHP 5, PHP 7, PHP 8)
Exception::getMessage—Obtiene el mensaje de Excepción
Devuelve el mensaje de Excepción.
Esta función no tiene parámetros.
Devuelve el mensaje de Excepción en formato cadena.
Ejemplo #1 Ejemplo deException::getMessage()
<?php
try {
throw newException("Algún mensaje de error");
} catch(Exception $e) {
echo$e->getMessage();
}
?>El resultado del ejemplo sería algo similar a:
Algún mensaje de error
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Exception::getPrevious—Devuelve la excepción anterior
Devuelve la excepción anterior (el tercer parámetro deException::__construct()).
Esta función no tiene parámetros.
Devuelve laThrowableanterior si está disponible onullsi no.
| Versión | Descripción |
|---|---|
| 7.0.0 | La declaración de tipo de retorno cambió aThrowable. |
Ejemplo #1 Ejemplo deException::getPrevious()
Recorrer, e imprimir la traza de una excepción.
<?php
classMiPropiaExcepciónextendsException{}
functionhacerCosas() {
try {
throw newInvalidArgumentException("¡Lo está haciendo mal!",112);
} catch(Exception $e) {
throw newMiPropiaExcepción("Ocurrió algo",911,$e);
}
}
try {
hacerCosas();
} catch(Exception $e) {
do {
printf("%s:%d %s (%d) [%s]\n",$e->getFile(),$e->getLine(),$e->getMessage(),$e->getCode(),get_class($e));
} while($e=$e->getPrevious());
}
?>El resultado del ejemplo sería algo similar a:
/home/bjori/ex.php:8 Ocurrió algo (911) [MiPropiaExcepción] /home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentException]
(PHP 5, PHP 7, PHP 8)
Exception::getCode—Obtiene el código de una excepción
Esta función no tiene parámetros.
Devuelve el código de Excepción en forma deintegerenExceptionpero posiblemente en forma de otros tipos enExceptiondescendientes (por ejemplo comostringenPDOException).
Ejemplo #1 Ejemplo deException::getCode()
<?php
try {
throw newException("Un mensaje de error",30);
} catch(Exception $e) {
echo"El código de excepción es: ".$e->getCode();
}
?>El resultado del ejemplo sería algo similar a:
El código de excepción es: 30
(PHP 5, PHP 7, PHP 8)
Exception::getFile—Obtiene el fichero en el que se creó la excepción
Obtiene el nombre del fichero en el que fue creada la excepción.
Esta función no tiene parámetros.
Devuelve el nombre del fichero en donde fue creada la excepción.
Ejemplo #1 Ejemplo deException::getFile()
<?php
try {
throw newException;
} catch(Exception $e) {
echo$e->getFile();
}
?>El resultado del ejemplo sería algo similar a:
/home/bjori/tmp/ex.php
(PHP 5, PHP 7, PHP 8)
Exception::getLine—Obtiene la línea en el que se creó la excepción
Devuelve el número de la línea donde se creó la excepción.
Esta función no tiene parámetros.
Devuelve el número de la línea donde se creó la excepción.
Ejemplo #1 Ejemplo deException::getLine()
<?php
try {
throw newException("Algún mensaje de error");
} catch(Exception $e) {
echo"La excepción se creó en la línea: ".$e->getLine();
}
?>El resultado del ejemplo sería algo similar a:
La excepción se creó en la línea: 3
(PHP 5, PHP 7, PHP 8)
Exception::getTrace—Obtiene la traza de la pila
Devuelve la traza de pila de una excepción.
Esta función no tiene parámetros.
Devuelve el seguimiento de pila de una excepción como unarray.
Ejemplo #1 Ejemplo deException::getTrace()
<?php
functiontest() {
throw newException;
}
try {
test();
} catch(Exception $e) {
var_dump($e->getTrace());
}
?>El resultado del ejemplo sería algo similar a:
array(1) {
[0]=>
array(4) {
["file"]=>
string(22) "/home/bjori/tmp/ex.php"
["line"]=>
int(7)
["function"]=>
string(4) "test"
["args"]=>
array(0) {
}
}
}
(PHP 5, PHP 7, PHP 8)
Exception::getTraceAsString—Obtiene la traza de la pila como una cadena de caracteres
Devuelve la traza de la pila de una excepción como una cadena de caracteres.
Esta función no tiene parámetros.
Returns the Exception stack trace as a string.
Ejemplo #1 Ejemplo deException::getTraceAsString()
<?php
functiontest() {
throw newException;
}
try {
test();
} catch(Exception $e) {
echo$e->getTraceAsString();
}
?>El resultado del ejemplo sería algo similar a:
#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}
(PHP 5, PHP 7, PHP 8)
Exception::__toString—Representación de la excepción en formato cadena
Devuelve la representación de la excepción en formatostring.
Esta función no tiene parámetros.
Devuelve la representación de la excepción en formatostring.
Ejemplo #1 Ejemplo deException::__toString()
<?php
try {
throw newException("Some error message");
} catch(Exception $e) {
echo$e;
}
?>El resultado del ejemplo sería algo similar a:
exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}
(PHP 5, PHP 7, PHP 8)
Exception::__clone—Clona la excepción
Intenta clonar la Excepción, lo que resultará en un error Fatal.
Esta función no tiene parámetros.
No devuelve ningún valor.
Las Excepcionesnose pueden clonar.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
Una excepción de error.
$message= "",$code= 0,$severity= E_ERROR,$filename= __FILE__,$lineno= __LINE__,$previous=nullLa gravedad de la excepción
Ejemplo #1 Utilizarset_error_handler()para convertir mensajes de error en objetos ErrorException.
<?php
functionexception_error_handler($severidad,$mensaje,$fichero,$línea) {
if (!(error_reporting() &$severidad)) {
// Este código de error no está incluido en error_reporting
return;
}
throw newErrorException($mensaje,0,$severidad,$fichero,$línea);
}
set_error_handler("exception_error_handler");
/* Desencadenar la excepción */
strpos();
?>El resultado del ejemplo sería algo similar a:
Fatal error: Uncaught exception 'ErrorException' with message 'strpos() expects at least 2 parameters, 0 given' in /home/bjori/tmp/ex.php:12
Stack trace:
#0 [internal function]: exception_error_handler(2, 'strpos() expect...', '/home/bjori/php...', 12, Array)
#1 /home/bjori/php/cleandocs/test.php(12): strpos()
#2 {main}
thrown in /home/bjori/tmp/ex.php on line 12
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
ErrorException::__construct—Constructor de la excepción
$message= "",$code= 0,$severity= E_ERROR,$filename= __FILE__,$lineno= __LINE__,$previous=nullConstruye el objeto Exception.
messageMensaje de la excepción a lanzar.
codeEl código de la excepción.
severityNivel de la severidad de la excepción.
Nota:
Aunque la severidad puede ser cuaquier valor de tipointeger, se pretende que se empleen lasconstantes de error.
filenameNombre del fichero donde se lanzó la excepción.
linenoNúmero de la línea donde se produjo la excepción.
previousLa anterior excepción utilizada para la excepción de encadenamiento.
| Versión | Descripción |
|---|---|
| 5.3.0 | El parámetropreviousfue añadido. |
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
ErrorException::getSeverity—Obtiene la severidad de la excepción
Devuelve la severidad de la excepción.
Esta función no tiene parámetros.
Devuelve el nivel de la severidad de la excepción.
Ejemplo #1 Ejemplo deErrorException::getSeverity()
<?php
try {
throw newErrorException("Mensaje de la excepción",0,E_USER_ERROR);
} catch(ErrorException $e) {
echo"La severidad de la excepción es: ".$e->getSeverity();
var_dump($e->getSeverity() ===E_USER_ERROR);
}
?>El resultado del ejemplo sería algo similar a:
La severidad de la excepción es: 256 bool(true)
(PHP 7, PHP 8)
Errores la clase base para todos los errores de PHP internos.
El mensaje de error
El código de error
El nombre del fichero donde ocurrió el error
La línea donde ocurrió el error
(PHP 7, PHP 8)
Error::__construct—Construir el objeto error
Construye el Error.
messageEl mensaje de error.
codeEl código de error.
previousEl objeto Throwable anterior empleado para la cadena de excepciones.
Nota:
El parámetro
messageNOes seguro a nivel binario.
(PHP 7, PHP 8)
Error::getMessage—Obtener el mensaje de error
Devuelve el mensaje de error.
Esta función no tiene parámetros.
Devuelve el mensaje de error como una cadena.
Ejemplo #1 Ejemplo deError::getMessage()
<?php
try {
throw newError("Un mensaje de error");
} catch(Error $e) {
echo$e->getMessage();
}
?>El resultado del ejemplo sería algo similar a:
Un mensaje de error
(PHP 7, PHP 8)
Error::getPrevious—Devuelve el objeto Throwable anterior
Devuelve el objeto Throwable anterior (el tercer parámetro deError::__construct()).
Esta función no tiene parámetros.
Devuelve el objetoThrowableanterior si está disponible, onullen caso contrario.
Ejemplo #1 Ejemplo deError::getPrevious()
Recorrer e imprimir la traza de errores.
<?php
classMiErrorPersonalizadoextendsError{}
functionhacerCosas() {
try {
throw newInvalidArgumentError("¡Lo está haciendo mal!",112);
} catch(Error $e) {
throw newMiErrorPersonalizado("Ocurrió algo",911,$e);
}
}
try {
hacerCosas();
} catch(Error $e) {
do {
printf("%s:%d %s (%d) [%s]\n",$e->getFile(),$e->getLine(),$e->getMessage(),$e->getCode(),get_class($e));
} while($e=$e->getPrevious());
}
?>El resultado del ejemplo sería algo similar a:
/home/bjori/ex.php:8 Ocurrió algo (911) [MiErrorPersonalizado] /home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentError]
(PHP 7, PHP 8)
Error::getCode—Obtener el código de error
Esta función no tiene parámetros.
Devuelve el código de error como uninteger
Ejemplo #1 Ejemplo deError::getCode()
<?php
try {
throw newError("Un mensaje de error",30);
} catch(Error $e) {
echo"El código del Error es: ".$e->getCode();
}
?>El resultado del ejemplo sería algo similar a:
El código del Error es: 30
(PHP 7, PHP 8)
Error::getFile—Obtener el fichero en el que ocurrío el error
Obtiene el nombre del fichero donde ocurrió el error.
Esta función no tiene parámetros.
Devuelve el nombre del fichero el en cual ocurrió el error.
Ejemplo #1 Ejemplo deError::getFile()
<?php
try {
throw newError;
} catch(Error $e) {
echo$e->getFile();
}
?>El resultado del ejemplo sería algo similar a:
/home/bjori/tmp/ex.php
(PHP 7, PHP 8)
Error::getLine—Obtener la línea en la que ocurrió el error
Obtiene el número de línea donde ocurrió el error.
Esta función no tiene parámetros.
Devuelve el número de línea en la que ocurrió el error.
Ejemplo #1 Ejemplo deError::getLine()
<?php
try {
throw newError("Un mensaje de error");
} catch(Error $e) {
echo"El error se ocasionó en la línea: ".$e->getLine();
}
?>El resultado del ejemplo sería algo similar a:
El error se ocasionó en la línea: 3
(PHP 7, PHP 8)
Error::getTrace—Obtener la traza de la pila
Devuelve la traza de la pila.
Esta función no tiene parámetros.
Devuelve la traza de la pila como unarray.
Ejemplo #1 Ejemplo deError::getTrace()
<?php
functionprueba() {
throw newError;
}
try {
prueba();
} catch(Error $e) {
var_dump($e->getTrace());
}
?>El resultado del ejemplo sería algo similar a:
array(1) {
[0]=>
array(4) {
["file"]=>
string(22) "/home/bjori/tmp/ex.php"
["line"]=>
int(7)
["function"]=>
string(6) "prueba"
["args"]=>
array(0) {
}
}
}
(PHP 7, PHP 8)
Error::getTraceAsString—Obtener la traza de la pila como un string
Devuelve la traza de la pila como un string.
Esta función no tiene parámetros.
Devuelve la traza de la pila como un string.
Ejemplo #1 Ejemplo deError::getTraceAsString()
<?php
functionprueba() {
throw newError;
}
try {
prueba();
} catch(Error $e) {
echo$e->getTraceAsString();
}
?>El resultado del ejemplo sería algo similar a:
#0 /home/bjori/tmp/ex.php(7): prueba()
#1 {main}
(PHP 7, PHP 8)
Error::__toString—Representación de string del error
Devuelve la representación destringdel error.
Esta función no tiene parámetros.
Devuelve la representación destringdel error.
Ejemplo #1 Ejemplo deError::__toString()
<?php
try {
throw newError("Un mensaje de error");
} catch(Error $e) {
echo$e;
}
?>El resultado del ejemplo sería algo similar a:
Error: Un mensaje de error in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}
(PHP 7, PHP 8)
Error::__clone—Clonar el error
Un error no se pueden clonar, por lo que este método resulta en un error fatal.
Esta función no tiene parámetros.
No devuelve ningún valor.
Los erroresnoson clonabes.
(PHP 7 >= PHP 7.1.0, PHP 8)
ArgumentCountErrores lanzado cuando muy pocos argumentos son pasados a una funcion o método definido por el usuario.
(PHP 7, PHP 8)
UnArithmeticErrores lanzado cuando ocurre un error durante la realización de operaciones matemáticas. En PHP 7.0, estos errores incluyen el intento de realizar un desplazamiento de bit mediante una cantidad negativa, y cualquier llamada aintdiv()que resulte en un valor fuera de los límites posibles de uninteger.
(PHP 7, PHP 8)
UnAssertionErrorse lanza cuando falla una afirmación realizada medianteassert().
(PHP 7, PHP 8)
UnDivisionByZeroErrorse lanza al intentar dividir un número por cero.
(PHP 7 > 7.3.0, PHP 8)
CompileErrores lanzado por algunos errores de compilación, que anteriormente emitió un error fatal.
(PHP 7, PHP 8)
UnParseErrorse lanza cuando ocurre un error al analizar código de PHP, tal como cuando se llama aeval().
Nota:ParseErrorextiendeCompileErrora partir de PHP 7.3.0. Anteriormente, extendíaError.
(PHP 7, PHP 8)
Existen tres escenarios donde de podría lanzar unTypeError. El primero es donde el tipo de argumento pasado a una función no coincide con su correspondiente tipo de parámetro declarado. El segundo es donde un valor devuelto desde una función no coincide con el tipo de devolución declarado en la función. El tercero es donde se proporciona un número inválido de argumentos a una función interna de PHP (solamente en modo estricto).
Véanse también lasinterfaces de la SPLy lasclases reservadas.
(PHP 5, PHP 7, PHP 8)
Interfaz para detectar si una clase puede recorrerse medianteforeach.
Una interfaz abstracta base no puede ser implementada sola. En su lugar, debe ser implementada conIteratorAggregateo conIterator.
Nota:
Las clases internas que implementan esta interfaz pueden ser usadas en una construcciónforeachy no necesitan implementarIteratorAggregateoIterator.
Nota:
Esta es una interfaz del motor interno que no puede ser implementada en scripts de PHP. Se debe emplear en su lugar oIteratorAggregate, o bienIterator. Cuando se implementa una interfaz que extiende a Traversable, asegúrese de enumerarIteratorAggregateoIteratorantes de su nombre en la cláusula de implementación.
Esta interfaz no tiene métodos; su único propósito es servir de interfaz base para todas las clases que se pueden recorrer.
(PHP 5, PHP 7, PHP 8)
Interfaz para iteradores externos u objetos que pueden ser iterados internamente por sí mismos.
PHP ya ofrece un número de iteradores para muchas de las tareas del día a día. Véase la lista deiteradores SPL.
Ejemplo #1 Uso básico
Este ejemplo muestra el orden en el que se llaman a los métodos cuando se emplea unforeachcon un iterator.
<?php
classmyIteratorimplementsIterator{
private$position=0;
private$array= array(
"firstelement",
"secondelement",
"lastelement",
);
public function__construct() {
$this->position=0;
}
public functionrewind() {
var_dump(__METHOD__);
$this->position=0;
}
public functioncurrent() {
var_dump(__METHOD__);
return$this->array[$this->position];
}
public functionkey() {
var_dump(__METHOD__);
return$this->position;
}
public functionnext() {
var_dump(__METHOD__);
++$this->position;
}
public functionvalid() {
var_dump(__METHOD__);
return isset($this->array[$this->position]);
}
}
$it= newmyIterator;
foreach($itas$key=>$value) {
var_dump($key,$value);
echo"\n";
}
?>El resultado del ejemplo sería algo similar a:
string(18) "myIterator::rewind" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(0) string(12) "firstelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(1) string(13) "secondelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(2) string(11) "lastelement" string(16) "myIterator::next" string(17) "myIterator::valid"
(PHP 5, PHP 7, PHP 8)
Iterator::current—Devuelve el elemento actual
Esta función no tiene parámetros.
Puede devolver cualquier tipo.
(PHP 5, PHP 7, PHP 8)
Iterator::key—Devuelve la clave del elemento actual
Devuelve la clave del elemento actual.
Esta función no tiene parámetros.
Devuelvescalaren caso de éxito, onullen caso de error.
Muestra unE_NOTICEen caso de error.
(PHP 5, PHP 7, PHP 8)
Iterator::next—Avanza al siguiente elemento
Avanza la posición actual al siguiente elemento.
Nota:
El método es llamadodespuésde cadaforeachloop.
Esta función no tiene parámetros.
El valor devuelto es ignorado.
(PHP 5, PHP 7, PHP 8)
Iterator::rewind—Rebobine la Iterator al primer elemento
Rebobina de nuevo al primer elemento de la Iterator.
Nota:
Este es elprimermétodo llamado cuando se inicia unforeachbucle.Nova a ser ejecutadodespuesforeachbucle.
Esta función no tiene parámetros.
Cualquier valor devuelto se pasa por alto.
(PHP 5, PHP 7, PHP 8)
Iterator::valid—Comprueba si la posición actual es válido
Este método se llama después deIterator::rewind()yIterator::next()para comprobar si la posición actual es válido.
Esta función no tiene parámetros.
El valor de retorno se debe fundir abooleany luego evaluar. Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5, PHP 7, PHP 8)
Para crear una interfaz externa Iterator.
Ejemplo #1 Uso básico
<?php
classmyDataimplementsIteratorAggregate{
public$property1="Public property one";
public$property2="Public property two";
public$property3="Public property three";
public function__construct() {
$this->property4="last property";
}
public functiongetIterator() {
return newArrayIterator($this);
}
}
$obj= newmyData;
foreach($objas$key=>$value) {
var_dump($key,$value);
echo"\n";
}
?>El resultado del ejemplo sería algo similar a:
string(9) "property1" string(19) "Public property one" string(9) "property2" string(19) "Public property two" string(9) "property3" string(21) "Public property three" string(9) "property4" string(13) "last property"
(PHP 5, PHP 7, PHP 8)
IteratorAggregate::getIterator—Recuperar un Iterator externo
Esta función no tiene parámetros.
Una instancia de un objeto que implementaIteratoroTraversable
Lanza unaExceptionen caso de fallo.
(PHP 7, PHP 8)
Throwablees la interfaz base para cualquier objeto que pueda ser lanzado mediante una sentenciathrowen PHP 7, incluyendoErroryException.
Nota:
Las clases de PHP no pueden implementar la interfazThrowabledirectamente, por lo que deben extender en su lugarException.
(PHP 7, PHP 8)
Throwable::getMessage—Obtiene el mensaje
Devuelve el mensaje asociado al objeto lanzado.
Esta función no tiene parámetros.
Devuelve el mensaje asociado al objeto lanzado.
(PHP 7, PHP 8)
Throwable::getCode—Obtener el código de la excepción
Devuelve el código de error asociado al objeto lanzado.
Esta función no tiene parámetros.
Devuelve el código de la excepción como unintegerenException, aunque posiblemente como otro tipo en los descendientes deException(por ejemplo, comostringenPDOException).
(PHP 7, PHP 8)
Throwable::getFile—Obtiene el fichero en el que se creó el objeto
Obtiene el nombre del fichero en el que se creó el objeto lanzado.
Esta función no tiene parámetros.
Devuelve el nombre del fichero en el que se creó la el objeto lanzado.
(PHP 7, PHP 8)
Throwable::getLine—Obtiene la línea en la que el objeto fue instanciado
Devuelve el número de línea en la que el objeto fue instanciado.
Esta función no tiene parámetros.
Devuelve el número de línea en la que el objeto fue instanciado.
(PHP 7, PHP 8)
Throwable::getTrace—Obtener la traza de la pila
Devuelve la traza de la pila como unarray.
Esta función no tiene parámetros.
Devuelve la traza de la pila como unarraycon el mismo formato que endebug_backtrace().
(PHP 7, PHP 8)
Throwable::getTraceAsString—Obtener la traza de la pila como un string
Esta función no tiene parámetros.
Devuelve la traza de la pila como un string.
(PHP 7, PHP 8)
Throwable::getPrevious—Devuelve el objeto Throwable previo
Devuelve el objeto Throwable previo (por ejemplo, uno proporcionado como tercer parámetro deException::__construct()).
Esta función no tiene parámetros.
Devuelve el objetoThrowableanterior si está disponible, onullsi no lo está.
(PHP 7, PHP 8)
Throwable::__toString—Obtiene un representación de string del objeto lanzado
Esta función no tiene parámetros.
Devuelve la representación destringdel objeto lanzado.
(PHP 5, PHP 7, PHP 8)
Interfaz para proporcionar acceso a objetos como arrays.
Ejemplo #1 Uso básico
<?php
classObjimplementsArrayAccess{
private$contenedor= array();
public function__construct() {
$this->contenedor= array(
"uno"=>1,
"dos"=>2,
"tres"=>3,
);
}
public functionoffsetSet($offset,$valor) {
if (is_null($offset)) {
$this->contenedor[] =$valor;
} else {
$this->contenedor[$offset] =$valor;
}
}
public functionoffsetExists($offset) {
return isset($this->contenedor[$offset]);
}
public functionoffsetUnset($offset) {
unset($this->contenedor[$offset]);
}
public functionoffsetGet($offset) {
return isset($this->contenedor[$offset]) ?$this->contenedor[$offset] :null;
}
}
$obj= newObj;
var_dump(isset($obj["dos"]));
var_dump($obj["dos"]);
unset($obj["dos"]);
var_dump(isset($obj["dos"]));
$obj["dos"] ="Un valor";
var_dump($obj["dos"]);
$obj[] ='Añadido 1';
$obj[] ='Añadido 2';
$obj[] ='Añadido 3';
print_r($obj);
?>El resultado del ejemplo sería algo similar a:
bool(true)
int(2)
bool(false)
string(8) "Un valor"
obj Object
(
[contenedor:obj:private] => Array
(
[uno] => 1
[tres] => 3
[dos] => Un valor
[0] => Añadido 1
[1] => Añadido 2
[2] => Añadido 3
)
)
(PHP 5, PHP 7, PHP 8)
ArrayAccess::offsetExists—Comprobar si existe un índice
Comprueba si existe o no un índice.
Este método se ejecuta cuando se utilizan las funcionesisset()oempty()sobre los objetos que implementanArrayAccess.
Nota:
Cuando se utilizaempty(),ArrayAccess::offsetGet()será invocada para comprobar si está vacío solamente siArrayAccess::offsetExists()devuelve
true.
offsetEl índice a comprobar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
El valor de retorno se debe convertir abooleansi no devuelve un valor boleano.
Ejemplo #1 Ejemplo deArrayAccess::offsetExists()
<?php
classobjimplementsarrayaccess{
public functionoffsetSet($offset,$value) {
var_dump(__METHOD__);
}
public functionoffsetExists($var) {
var_dump(__METHOD__);
if ($var=="foobar") {
returntrue;
}
returnfalse;
}
public functionoffsetUnset($var) {
var_dump(__METHOD__);
}
public functionoffsetGet($var) {
var_dump(__METHOD__);
return"value";
}
}
$obj= newobj;
echo"Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));
echo"\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));
echo"\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>El resultado del ejemplo sería algo similar a:
Runs obj::offsetExists() string(17) "obj::offsetExists" bool(true) Runs obj::offsetExists() and obj::offsetGet() string(17) "obj::offsetExists" string(14) "obj::offsetGet" bool(false) Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get string(17) "obj::offsetExists" bool(true)
(PHP 5, PHP 7, PHP 8)
ArrayAccess::offsetGet—Offset para recuperar
Devuelve el valor correspondiente a desplazamiento especificado.
Este método se ejecuta para comprobar si el desplazamiento esempty().
offsetEl desplazamiento va a recuperar.
Nota:
A partir de PHP 5.3.4, el prototipo de los controles se relajaron y es posible para las implementaciones de este método para devolver por referencia. Esto hace que las modificaciones indirectas a las dimensiones de los arreglos sobrecargados de objetosArrayAccessposibles.
Una modificación directa es aquella que reemplaza completamente el valor de la dimensión de el arreglo, como en
$obj[6] = 7. Una modificación indirecta, por el contrario, sólo una parte los cambios de la dimensión, o los intentos de asignar la dimensión en función de otra variable, como en$obj[6][7] = 7o$var =& $obj[6]. Con incrementos++y disminye con--también se aplican de una manera que requiere la modificación indirecta.Si bien la modificación directa desencadena una llamada aArrayAccess::offsetSet(), modificación indirecta provoca una llamada aArrayAccess::offsetGet(). En ese caso, la aplicación deArrayAccess::offsetGet()debe ser capaz de volver por la referencia, de lo contrario un
E_NOTICEmensaje es elevado..
Puede devolver todos los tipos de valor.
(PHP 5, PHP 7, PHP 8)
ArrayAccess::offsetSet—Asignar un valor al índice esepecificado
Asigna un valor a un offset determinado.
offsetEl offset al que se asigna el valor.
valueEl valor a asignar.
No devuelve ningún valor.
Nota:
El parámetro
offsetserá inicializado anullsi otro valor no está disponible, como en el siguiente ejemplo.<?php
$arrayaccess[] ="primer valor";
$arrayaccess[] ="segundo valor";
print_r($arrayaccess);
?>El resultado del ejemplo sería:
Array ( [0] => primer valor [1] => segundo valor )
Nota:
Esta función no es invocada al realizar asignaciones por referencias y por tanto en los cambios de dimensiones en arrays sobrecargados conArrayAccess(indirecto en el sentido de que no se hace cambiando la dimensión directamente, sino cambiando una sub-dimensión o sub-propiedad o asignando la dimensión del array por referencia en otra variable). En su lugar, se llama aArrayAccess::offsetGet(). La operación tendrá éxito si devuelve el valor por referencia, lo cuál sólo es posible desde PHP 5.3.4.
(PHP 5, PHP 7, PHP 8)
ArrayAccess::offsetUnset—Destruye un offset
Destruye un offset.
Nota:
Este métodonoserá llamado cuando se fuerza un tipo mediante(unset)
offsetEl offset a destruir.
No devuelve ningún valor.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
Interfaz para personalizar la serialización.
Las clases que implementan esta interfaz ya no admiten__sleep()ni__wakeup(). El método serialize se llama cuando una instancia requiere ser serializada. Esto no invoca a __destruct() ni tiene ningún efecto adicional a menos que se programe dentro del método. Cuando los datos son deserializados, la clase es conocida y se llama al correspondiente método unserialize() como constructor en lugar de llamar al método __construct(). Se puede ejecutar el constructor estándar en el método si fuera necesario.
Ejemplo #1 Uso básico
<?php
classobjimplementsSerializable{
private$datos;
public function__construct() {
$this->datos="Mis datos privados";
}
public functionserialize() {
returnserialize($this->datos);
}
public functionunserialize($datos) {
$this->datos=unserialize($datos);
}
public functiongetDatos() {
return$this->datos;
}
}
$obj= newobj;
$ser=serialize($obj);
var_dump($ser);
$obj_nuevo=unserialize($ser);
var_dump($obj_nuevo->getDatos());
?>El resultado del ejemplo sería algo similar a:
string(38) "C:3:"obj":23:{s:15:"Mis datos privados";}"
string(15) "Mis datos privados"
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
Serializable::serialize—Representación en formato cadena de un objeto
Devuelve la representación de un objeto en formato string.
Esta función no tiene parámetros.
Devuelve la representación de un objeto onull
Lanza unaExceptioncuando de devuelen otros tipos aparte de string ynull
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
Serializable::unserialize—Construye el objeto
$serialized):voidEs llamado durante la unserialización del objeto.
Nota:
Este método actua como elconstructordel objeto. El método__construct()noserá llamado después de este método.
serializedLa representación en formato string de un objeto.
El valor devuelto por este método es ignorado.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Clase empleada para representarfunciones anónimas.
Las funciones anónimas, implementadas en PHP 5.3, producían objetos de este tipo. Este hecho solía ser considerado como un detalle de implementación, pero ahora puede confiarse en él. Desde PHP 5.4, esta clase tiene métodos que permiten más control sobre las funciones anónimas después de haber sido creadas.
Además de los métodos listados aquí, esta clase también posse un método__invoke. Está por consistencia con otras clases que implementan lallamada mágica, ya que este método no se usa para llamar a la función.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Closure::__construct—Constructor que anula la instanciación
Este método sólo existe para anular la instanciación de la claseClosure. Los objetos de esta clase se crean del modo descrito en la páginafunciones anónimas.
Esta función no tiene parámetros.
Este método no tiene un valor de retorno; simplemente emite un error (de tipoE_RECOVERABLE_ERROR).
(PHP 5 >= 5.4.0, PHP 7, PHP 8)
Closure::bind—Duplicar un cierre con un objeto vinculado y ámbito de clase especificados
Este método es una versión estática deClosure::bindTo(). Véase la documentación de ese método para más información.
closureLa función anónima a vincular.
newthisEl objeto al que la función anónima dada debería ser vinculado, onullpara que el cierre sea desvinculado.
newscopeEl ámbito de clase a la que asociar el cierre, o 'static' para mantener el actual. Si se proporciona un objeto, el tipo del mismo se usará en su lugar. Esto determina la visibilidad de métodos protegidos y privados del objeto vinculado. No se permite pasar (un objeto de) una clase interna a este parámetro.
Devuelve un nuevo objetoClosureofalseen caso de error
| Versión | Descripción |
|---|---|
| 7.0.0 | newscopeya no puede ser (un objeto de) una clase interna, lo que era posible antes de esta versión. |
Ejemplo #1 Ejemplo deClosure::bind()
<?php
classA{
private static$sfoo=1;
private$ifoo=2;
}
$cl1= static function() {
returnA::$sfoo;
};
$cl2= function() {
return$this->ifoo;
};
$bcl1=Closure::bind($cl1,null,'A');
$bcl2=Closure::bind($cl2, newA(),'A');
echo$bcl1(),"\n";
echo$bcl2(),"\n";
?>El resultado del ejemplo sería algo similar a:
1 2
(PHP 5 >= 5.4.0, PHP 7, PHP 8)
Closure::bindTo—Duplicar el cierre con un objeto vinculado y ámbito de clase nuevos
Crea y devuelve una nuevafunción anónimacon el cuerpo y variables vinculadas como ésta, pero posiblemente con un objeto vinculado diferente y un nuevo ámbito de clase.
El "objeto vinculado" determina el valor que$thistendrá en el cuerpo de la función, y el "ámbito de clase" representa una clase que determina los miembros privados y protegidos a los que será capaz de acceder la función anónima. Concretamente, los miembros que serán visibles son los mismos que si la función anónima fuese un método de la clase dada como valor del parámetronewscope.
Los cierres estáticos no pueden tener ningún objeto vinculado (el valor del parámetronewthisdebería sernull), pero esta función puede, no obstante, usarse para cambiar su ámbito de clase.
Esta función se asegurará de que a un cierre no estático que tenga una instancia vinculada se le aplique un ámbito y viceversa. En este punto, los cierres no estáticos que le son dados un ámbito, excepto una instancianull, son hechos estáticos, y los cierres no estáticos y sin ámbito que le son dados una instancia no nula se les aplica un ámbito de clase no especificado.
Nota:
Si solamente se quieren duplicar las funciones anónimas, se puede usarcloningen su lugar.
newthisEl objeto al que la función anónima dada debería ser vinculado, onullpara que el cierre sea desvinculado.
newscopeEl ámbito de la clase a la que se va a asociar el cierre, o 'static' para mantener el actual. Si se proporciona un objeto, el tipo del mismo se usará en su lugar. Esto determina la visibilidad de métodos protegidos y privados del objeto vinculado. No se permite pasar (un objeto de) una clase interna a este parémtro.
Devuelve el objetoClosurerecién creado ofalseen caso de error
| Versión | Descripción |
|---|---|
| 7.0.0 | newscopeya no puede ser (un objeto de) una clase interna, lo cual era posible antes de esta versión. |
Ejemplo #1 Ejemplo deClosure::bindTo()
<?php
classA{
function__construct($val) {
$this->val=$val;
}
functiongetClosure() {
//devuelve el cierre vinculado a este objeto y el ámbito
return function() { return$this->val; };
}
}
$ob1= newA(1);
$ob2= newA(2);
$cl=$ob1->getClosure();
echo$cl(),"\n";
$cl=$cl->bindTo($ob2);
echo$cl(),"\n";
?>El resultado del ejemplo sería algo similar a:
1 2
(PHP 7, PHP 8)
Closure::call—Vincula y llama al cierre
Vincula temporalmente el cierre anewthis, y lo llama con cualquier parámetro dado.
newthisElobjecta vincular al cierre mientras dure la llamada.
...Cero o más parámetros, que serán dados como parámetros al cierre.
Devuelve el valor devuelto por el cierre.
Ejemplo #1 Ejemplo deClosure::call()
<?php
classValor{
protected$valor;
public function__construct($valor) {
$this->valor=$valor;
}
public functiongetValor() {
return$this->valor;
}
}
$tres= newValor(3);
$cuatro= newValor(4);
$cierre= function ($delta) {var_dump($this->getValor() +$delta); };
$cierre->call($tres,4);
$cierre->call($cuatro,4);
?>El resultado del ejemplo sería:
int(7) int(8)
(PHP 7 >= 7.1.0)
Closure::fromCallable—Convierte un 'callable' en un cierre
Crea y devuelve una nuevafunción anónimadesde elcallabledado empleando el ámbito actual. Este método comprueba sicallablees llamable en el ámbito actual, lanzando unTypeErrorsi no lo es.
callableEl «callable» a convertir.
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Los objetosGeneratorson devueltos desdegeneradores.
Los objetosGeneratorno pueden ser instanciados mediantenew.
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::current—Obtener el valor producido
Esta función no tiene parámetros.
Devuelve el valor producido.
(PHP 7, PHP 8)
Generator::getReturn—Obtener el valor devuelto de un generador
Esta función no tiene parámetros.
Devuelve el valor devuelto del generador una vez ha finalizado su ejecución.
Ejemplo #1 Ejemplo deGenerator::getReturn()
<?php
$gen= (function() {
yield1;
yield2;
return3;
})();
foreach ($genas$val) {
echo$val,PHP_EOL;
}
echo$gen->getReturn(),PHP_EOL;El resultado del ejemplo sería:
1 2 3
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::key—Obtener la clave generada
Esta función no tiene parámetros.
Devuelve la clave generada.
Ejemplo #1 Ejemplo deGenerator::key()
<?php
functionGen()
{
yield'key'=>'value';
}
$gen=Gen();
echo"{$gen->key()}=>{$gen->current()}";El resultado del ejemplo sería:
key => value
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::next—Continua la ejecución del generador
Llamar aGenerator::next()tiene el mismo efecto que llamar aGenerator::send()connullcomo argumento.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::rewind—Rebobina el iterador
Si la iteración ya ha comenzado, lanzará una excepción.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::send—Enviar un valor al generador
Envía el valor dado al generador como resultado de la expresiónyieldactual y reanuda la ejecución del generador.
Si el generador no es una expresiónyielden el momento de invocar a este método, se permitirá avanzar a la primera expresiónyieldantes de enviar el valor. Por tanto, no es necesario «preparar» generadores de PHP con una llamada aGenerator::next()(como se hace en Python).
valueEl valor a enviar al generador. Este valor será el valor devuelto de la expresiónyielden la que está actualmente el generador.
Devuelve el valor producido.
Ejemplo #1 Empleo deGenerator::send()para inyectar valores
<?php
functionprinter() {
echo"¡Soy una impresora!".PHP_EOL;
while (true) {
$string= yield;
echo$string;
}
}
$printer=printer();
$printer->send('¡Hola mundo!');
$printer->send('¡Adiós mundo!');
?>El resultado del ejemplo sería:
¡Soy una impresora! ¡Hola mundo! ¡Adiós mundo!
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::throw—Lanzar una excepción dentro generador
Lanza una excepción dentro del generador y reanuda su ejecución. El comportamiento será el mismo que si la expresiónyieldactual fuera reemplazada con una sentenciathrow $exception.
Si el generador ya está cerrado al invocar a este método, la excepción será lanzada en su lugar en el contexto del invocador.
exceptionLa excepción a lanzar dentro del generador.
Devuelve el valor generado.
| Versión | Descripción |
|---|---|
| 7.0.0 | Ahora el parámetroexceptiontambién aceptaThrowable. |
Ejemplo #1 Lanzar una ecepión dentro de un generador
<?php
functiongen() {
echo"Foo\n";
try {
yield;
} catch (Exception $e) {
echo"Excepción:{$e->getMessage()}\n";
}
echo"Bar\n";
}
$gen=gen();
$gen->rewind();
$gen->throw(newException('Prueba'));
?>El resultado del ejemplo sería:
Foo Excepción: Prueba Bar
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::valid—Verificar si el iterador ha sido cerrado
Esta función no tiene parámetros.
Devuelvefalsesi el iterador ha sido cerrado. De lo contrario devuelvetrue.
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
Generator::__wakeup—Serialize callback
Lanza una excepción indicando que el generador no puede ser presentado.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 7 >= 7.4.0, PHP 8)
Las referencias débiles permiten al programador retener una referencia a un objeto que no impide que el objeto sea destruido. Son útiles para implementar estructuras de tipo cache.
WeakReferenceno puede ser serializado.
Ejemplo #1 Uso básico de WeakReference
<?php
$obj= newstdClass;
$weakref=WeakReference::create($obj);
var_dump($weakref->get());
unset($obj);
var_dump($weakref->get());
?>El resultado del ejemplo sería algo similar a:
object(stdClass)#1 (0) {
}
NULL
(PHP 7 >= 7.4.0, PHP 8)
WeakReference::__construct—Constructor que no permite la instanciación
Este método existe sólo para no permitir la instanciación de la claseWeakReference. Las referencias débiles deben ser instanciadas con el método factoryWeakReference::create().
Esta función no tiene parámetros.
(PHP 7 >= 7.4.0, PHP 8)
WeakReference::create—Crea una nueva referencia débil
Crea una nuevaWeakReference.
referentEl objeto a ser referenciado débilmente.
Devuelve el objeto recién instanciado.
(PHP 7 >= 7.4.0, PHP 8)
WeakReference::get—Obtiene un objeto débilmente referenciado
Se obtiene un objeto débilmente referenciado. Si el objeto ya ha sido destruido, devuelvenull.
Esta función no tiene parámetros.
Devuelve el referenciadoobject, onullsi el objeto ha sido destruido.
PHP provides some predefined attributes that can be used.
(PHP 8)
Attributes offer the ability to add structured, machine-readable metadata information on declarations in code: Classes, methods, functions, parameters, properties and class constants can be the target of an attribute. The metadata defined by attributes can then be inspected at runtime using theReflection APIs. Attributes could therefore be thought of as a configuration language embedded directly into code.
Attribute::TARGET_CLASSAttribute::TARGET_FUNCTIONAttribute::TARGET_METHODAttribute::TARGET_PROPERTYAttribute::TARGET_CLASS_CONSTANTAttribute::TARGET_PARAMETERAttribute::TARGET_ALLAttribute::IS_REPEATABLE(PHP 8)
Attribute::__construct—Construct a new Attribute instance
$flags= Attribute::TARGET_ALL)Constructs a newAttributeinstance.
flags(PHP 8 >= 8.2.0)
This attribute is used to mark classes that allowdynamic properties.
Dynamic properties are deprecated as of PHP 8.2.0, thus using them without marking the class with this attribute will emit a deprecation notice.
<?php
classDefaultBehaviour{ }
#[\AllowDynamicProperties]
classClassAllowsDynamicProperties{ }
$o1= newDefaultBehaviour();
$o2= newClassAllowsDynamicProperties();
$o1->nonExistingProp=true;
$o2->nonExistingProp=true;
?>Output of the above example in PHP 8.2:
Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10
(PHP 8 >= 8.2.0)
AllowDynamicProperties::__construct—Construct a new AllowDynamicProperties attribute instance
Constructs a newAllowDynamicPropertiesinstance.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation. In case the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a#[\ReturnTypeWillChange]attribute can be added to silence the deprecation notice.
(PHP 8 >= 8.1.0)
ReturnTypeWillChange::__construct—Construct a new ReturnTypeWillChange attribute instance
Esta función no tiene parámetros.
(PHP 8 >= 8.2.0)
This attribute is used to mark a parameter that is sensitive and should have its value redacted if present in a stack trace.
<?php
functiondefaultBehavior(
string $secret,
string $normal
) {
throw newException('Error!');
}
functionsensitiveParametersWithAttribute(
#[\SensitiveParameter]
string $secret,
string $normal
) {
throw newException('Error!');
}
try {
defaultBehavior('password','normal');
} catch (Exception $e) {
echo$e,PHP_EOL,PHP_EOL;
}
try {
sensitiveParametersWithAttribute('password','normal');
} catch (Exception $e) {
echo$e,PHP_EOL,PHP_EOL;
}
?>Output of the above example in PHP 8.2 is similar to:
Exception: Error! in example.php:7
Stack trace:
#0 example.php(19): defaultBehavior('password', 'normal')
#1 {main}
Exception: Error! in example.php:15
Stack trace:
#0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
#1 {main}
(PHP 8 >= 8.2.0)
SensitiveParameter::__construct—Construct a new SensitiveParameter attribute instance
Esta función no tiene parámetros.
PHP ofrece varias opciones y parámetros de contexto que pueden utilizarse con todos los sistemas de ficheros y envolturas de flujos. Un contexto se crea constream_context_create(). Las opciones se establecen constream_context_set_option(), y los parámetros constream_context_set_params().
Opciones de contexto de sockets—Listado de opciones de contexto de sockets
Las opciones de contexto de sockets están disponibles para todas las envolturas que trabajan sobre sockets, comotcp,httpyftp.
| Versión | Descripción |
|---|---|
| 5.3.3 | Se agregóbindto. |
| 5.1.0 | Se agregóbacklog. |
Ejemplo #1 Ejemplo de uso básico debindto
<?php
// conectarse a internet usando la IP '192.168.0.100'
$opciones= array(
'socket'=> array(
'bindto'=>'192.168.0.100:0',
),
);
// conectarse a internet usando la IP '192.168.0.100' y el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'192.168.0.100:7000',
),
);
// conectarse a internet usando la dirección IPv6 '2001:db8::1'
// y el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'[2001:db8::1]:7000',
),
);
// conectarse a internet usando el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'0:7000',
),
);
// crear el contexto...
$contexto=stream_context_create($opciones);
// ...y usarlo para recuperar los datos
echofile_get_contents('http://www.example.com',false,$contexto);
?>Opciones de contexto de HTTP—Listado de opciones de contexto de HTTP
Opciones de contexto para los transporteshttp://yhttps://.
| Versión | Descripción |
|---|---|
| 5.3.4 | Se añadiófollow_location. |
| 5.3.0 | La opciónprotocol_versionadmite la decodificación de transferencias fragmentadas en caso de valer1.1. |
| 5.2.10 | Se añadióignore_errors. |
| 5.2.10 | El parámetroheaderahora puede ser unarrayde índices numéricos. |
| 5.2.1 | Se añadiótimeout. |
| 5.1.0 | Se añadió el soporte de HTTPS mediante proxies HTTP. |
| 5.1.0 | Se añadiómax_redirects. |
| 5.1.0 | Se añadióprotocol_version. |
Ejemplo #1 Obtener una página y enviar datos POST
<?php
$datos_post=http_build_query(
array(
'var1'=>'contenido',
'var2'=>'doh'
)
);
$opciones= array('http'=>
array(
'method'=>'POST',
'header'=>'Content-type: application/x-www-form-urlencoded',
'content'=>$datos_post
)
);
$contexto=stream_context_create($opciones);
$resultado=file_get_contents('http://example.com/submit.php',false,$contexto);
?>Ejemplo #2 Ignorar las redirecciones, aunque obtener las cabeceras y el contenido
<?php
$url="http://www.example.org/header.php";
$opciones= array('http'=>
array(
'method'=>'GET',
'max_redirects'=>'0',
'ignore_errors'=>'1'
)
);
$contexto=stream_context_create($opciones);
$flujo=fopen($url,'r',false,$contexto);
// información de cabeceras y meta datos
// sobre el flujo
var_dump(stream_get_meta_data($flujo));
// datos reales en $url
var_dump(stream_get_contents($flujo));
fclose($flujo);
?>Nota:Opciones de contexto del flujo de socket subyacente
Se pueden admitir opciones de contexto adicionales mediante eltransporte subyacente. Para flujoshttp://, deben consultarse las opciones de contexto del transportetcp://. Para flujoshttps://, deben consultarse las opciones de contexto del transportessl://.
Nota:Línea de estado HTTP
Cuando esta envultura de flujo sigue una redirección, los datos enwrapper_datadevueltos porstream_get_meta_data()podrían no contener necesariamente la línea de estado HTTP que realmente se aplica a los datos del contenido del índice0.La primera petición devolvió unarray ( 'wrapper_data' => array ( 0 => 'HTTP/1.0 301 Moved Permantenly', 1 => 'Cache-Control: no-cache', 2 => 'Connection: close', 3 => 'Location: http://example.com/foo.jpg', 4 => 'HTTP/1.1 200 OK', ...301(redirección permanente), de manera que la envoltura del flujo sigue automáticamente la redirección para obtener una respuesta de código200(índice =4).
Opciones de contexto para FTP—Listado de opciones de contexto para FTP
Opciones de contexto para transportesftp://yftps://
| Versión | Descripción |
|---|---|
| 5.1.0 | Se añadióproxy. |
Nota:Opciones subyacentes del contexto del flujo del socket
Opciones adicionales de contexto pueden se soportadas por eltransporte subyacentePara flujosftp://, remitirse a las opciones de contexto para el transportetcp://. Para flujosftps://, remitirse a las opciones de contexto para el transportessl://.
Opciones de contexto para SSL—Listado de opciones de contexto para SSL
Opciones de contexto para transportesssl://ytls://
| Versión | Descripción |
|---|---|
| 5.6.0 | Se añadieronpeer_fingerprintandverify_peer_name. El valor predeterminado deverify_peerse cambió atrue. |
| 5.4.13 | Se añadiódisable_compression. Requiere OpenSSL >= 1.0.0. |
| 5.3.2 | Se añadióSNI_enabledySNI_server_name. |
Nota:Debido a que
ssl://el es transporte subyacente para las envolturashttps://yftps://, cualquier opción de contexto que aplique parassl://también aplica parahttps://yftps://.
Nota:Para que SNI (Server Name Indication) esté disponible, entonces PHP se debe compilar con OpenSSL 0.9.8j o superior. Se utiliza
OPENSSL_TLSEXT_SERVER_NAMEpara determinar si SNI está soportado.
Opciones de contexto para CURL—Listado de opciones de contexto para CURL
Las opciones de contexto para CURL están disponibles cuando la extensiónCURLfue compilada usando la opción de configuración--with-curlwrappers.
Ejemplo #1 Obtener una página y enviar datos POST
<?php
$postdata=http_build_query(
array(
'var1'=>'some content',
'var2'=>'doh'
)
);
$opts= array('http'=>
array(
'method'=>'POST',
'header'=>'Content-type: application/x-www-form-urlencoded',
'content'=>$postdata
)
);
$context=stream_context_create($opts);
$result=file_get_contents('http://example.com/submit.php',false,$context);
?>Opciones de contexto Phar—Listado de opciones de contexto Phar
Opciones de contexto paraphar://envoltura.
Contexto parámetros—Listado de parámetros de contexto
Estosparametrosse pueden establecer en uncontextousando el la funciónstream_context_set_params().
Opciones del contexto zip—Listado de opciones del contexto zip
Las opciones del contexto zip están disponibles para envolturaszip.
| Versión | Descripción |
|---|---|
| PHP 7.2.0, PECL zip 1.14.0 | Se añadiópassword. |
Ejemplo #1 Ejemplo de uso básicopassword
<?php
// Leer el fichero encriptado
$opciones= array(
'zip'=> array(
'password'=>'secret',
),
);
// Crear el contexto...
$contexto=stream_context_create($opciones);
// ...y emplearlo para recuperar los datos
echofile_get_contents('zip://test.zip#test.txt", false, $ctx);
?>PHP incorpora de serie envolturas para distintos protocolos tipo URL para trabajar junto con funciones del sistema de ficheros, comofopen(),copy(),file_exists()yfilesize(). Además de estas envolturas, se pueden definir por el usuario utilizando la funciónstream_wrapper_register().
Nota:La sintaxis de URL que se utiliza para describir una envoltura solo puede ser
scheme://.... Las sintaxisscheme:/yscheme:no están soportadas.
file://—Acceso al sistema de ficheros local
ElSistema de Ficheroses la envoltura por omisión de PHP y representa al sistema de ficheros local. Cuando se proporciona una ruta relativa (esto es, no comienza con /, \, \\, ni con la letra de un dispositivo Windows) ésta se hará usando el directorio de trabajo actual. En muchos casos, se trata del directorio en el que se aloja el script, a no ser que se haya cambiado explicitamente. Si se utiliza la sapi CLI, apuntará al directorio desde el que se ejecutó el script.
En algunas funciones, como por ejemplofopen()ofile_get_contents(), puede usarse tambiéninclude_pathpara localizar ficheros con rutas relativas.
http://--https://—Acceso a URLS en HTTP(s)
Permite acceso de lectura a ficheros/recursos mediante HTTP 1.0, utilizando el método GET de HTTP. Junto con la petición, se envía una cabeceraHost:para así poder usar hosts virtuales basados en nombres. Si se ha definido unuser_agenten el ficherophp.inio en el contexto del flujo, éste se incluirá también en la petición.
El flujo proporciona acceso alcuerpodel recurso; las cabeceras se guardan en la variable$http_response_header.
Si fuera importante conocer la URL del recurso del que procede el documento (tras procesar todas las redirecciones), se deberán procesar todas las cabeceras de respuesta devueltas por el flujo.
Se usará la directivafromen la cabeceraFrom:siempre que esté asignado y no se sobrescriba porOpciones y parámetros de contexto.
Ejemplo #1 Detectar la URL en la que se finaliza tras las redirecciones
<?php
$url='http://www.example.com/redirecting_page.php';
$fp=fopen($url,'r');
$meta_data=stream_get_meta_data($fp);
foreach ($meta_data['wrapper_data'] as$response) {
/* Were we redirected? */
if (strtolower(substr($response,0,10)) =='location: ') {
/* update $url with where we were redirected to */
$url=substr($response,10);
}
}
?>Nota:Sólo habrá soporte para HTTPS cuando la extensiónopensslesté habilitada.
Las conexiones HTTP son de sólo lectura; no hay soporte para escribir o copiar datos a un recurso HTTP.
Se pueden enviar peticionesPOSTyPUT, por ejemplo, con ayuda de losContextos HTTP.
ftp://--ftps://—Acceso a URLs por FTP(s)
Permite tanto lectura de ficheros existentes como la creación de nuevos ficheros vía FTP. La conexión fallará si el servidor no soporta FTP en modo pasivo.
Se puede tanto leer como escribir ficheros, pero no las dos cosas simultáneamente. Si el fichero remoto ya existiera en el servidor ftp, y se quisiera abrir en modo escritura sin especificar la opción de contextooverwrite, también fallará la conexión. Si fuera necesario sobrescribir un fichero ya existente en ftp, se tendrá que especificar la opción de contextooverwriteantes de abrir el fichero para su escritura. Alternativamente, puede usarse laextensión FTP.
Si se ha establecido la directivafromenphp.ini, se enviará como contraseña para conexiones de FTP anónimo.
Nota:
Hay soporte para FTPS desde PHP 4.3.0, siempre y cuando se haya compilado con soporte paraopenssl.
Si el servidor no soporta SSL, entonces la conexión se restablece a una conexión ftp regular sin encriptación.
Nota:Añadiendo contenido
Se puede añadir contenido a los ficheros mediante la envoltura de URLftp://.
php://—Acceso a distintos flujos de E/S
PHP ofrece una serie de flujos de E/S generales que permiten acceder tanto a los flujos de entrada y salida de PHP, a la entrada estándar, a descriptores de ficheros de salida y de errores, a flujos de ficheros temporales en memoria y en disco, y a filtros para poder manipular otros recursos de ficheros según se lee desde o se escribe en ellos.
php://stdin,php://stdoutyphp://stderrpermiten acceder directamente al correspondiente flujo de entrada o salida del proceso de PHP. El flujo hace referencia a un descriptor de fichero duplicado, de modo que si se abrephp://stdiny más tarde se cierra, sólo se cerraría la copia del descriptor; el flujo real al que se refiereSTDINno se vería afectado. Tenga en cuenta que PHP mostraba un comportamiento irregular en este aspecto hasta PHP 5.2.1. Se recomienda utilizar simplemente las constantesSTDIN,STDOUTySTDERRen lugar de abrir flujos manualmente usando estas envolturas.
php://stdines de sólo lectura, mientras quephp://stdoutyphp://stderrson de sólo escritura.
php://inputes un flujo de sólo lectura que permite leer datos del cuerpo solicitado. En el caso de peticiones POST, es preferible usarphp://inputen vez de$HTTP_RAW_POST_DATAya que no depende de directivasphp.iniespeciales. Sin embargo, cuando no se genera automáticamente$HTTP_RAW_POST_DATA, se trata de una alternativa que hace un uso menos intensivo de memoria que activandoalways_populate_raw_post_data.php://inputno está disponible conenctype="multipart/form-data".
Nota:Antes de PHP 5.6, un flujo abierto conphp://inputsolamente podía leerse una vez; el flujo no admite operaciones de búsqueda. Sin embargo, dependiendo de la implementación de la SAPI, podría ser posible abrir otro flujophp://inputy reiniciar la lectura. Esto solamente es posible si los datos del cuerpo de la petición se han guardado. Este caso es típico en peticiones POST, pero no en otros métodos de petición, como PUT o PROPFIND.
php://outputes un flujo de sólo escritura que permite escribir en el buffer de salida tal como lo hacenprintyecho.
php://fdpermite el acceso directo al descriptor de archivo dado. Por ejemplo,php://fd/3refiere al descriptor de archivo 3.
php://memoryyphp://tempson flujos de lectura-escritura que permiten almacenar datos temporales en una envoltura similar a un fichero. La única diferencia entre las dos es quephp://memorysiempre almacenará sus datos en memoria, mientras quephp://temputilizará un fichero temporal cuando la cantidad de datos almacenados superen el límite predefinido (por omisión, 2 MB). La ubicación de este fichero temporal está determinada de la misma manera que la funciónsys_get_temp_dir(),
El límite de memoria dephp://tempse puede controlar añadiendo/maxmemory:NN, dondeNNes la cantidad en bytes máxima de datos a almacenar en memoria antes de recurrir a un fichero temporal.
php://filteres una especie de meta-envoltura diseñada para permitir aplicarfiltrosa los flujos en las aperturas. Esto es muy útil en las funciones todo en uno, comoreadfile(),file(), yfile_get_contents()donde, por otra parte, no se pueden aplicar filtros a los flujos antes de que se lea su contenido.
php://filteracepta los siguientes parámetros como parte de su ruta. Se pueden especifcar múltiples filtros en una ruta. Por favor, consulte los ejemplos para los usos concretors de estos parámetros.
| Nombre | Descripción |
|---|---|
resource=<flujo a filtrar> | Este parámetro es obligatorio. Especifica el flujo que se desea filtrar. |
read=<listra de filtros a aplicar a la cadena de lectura> | Este parámetro es opcional. Se pueden enumerar uno o más filtros, separados por el carácter|. |
write=<lista de filtros a aplicar a la cadena de escritura> | Este parámetro es opcional. Se puedene enumerar uno o más filtros, separados por el carácter|. |
<lista de filtros a aplicar a las dos cadenas> | Cualquier listra de filtros que no esté precedida ni porread=ni porwrite=se aplicará tanto a las cadenas de lectura como de escritura según proceda. |
| Versión | Descripción |
|---|---|
| 5.6.0 | php://inputse puede reutilzar. |
| 5.3.6 | Se añadióphp://fd. |
| 5.1.0 | Se añadieronphp://memoryyphp://temp. |
Ejemplo #1 php://temp/maxmemory
Este parámetro opcional permite establecer el límite de memoria a partir del cualphp://tempcomienza a usar un fichero temporal.
<?php
// Establecer el límite a 5 MB.
$fiveMBs=5*1024*1024;
$fp=fopen("php://temp/maxmemory:$fiveMBs",'r+');
fputs($fp,"hello\n");
// Leer lo que hemos escrito.
rewind($fp);
echostream_get_contents($fp);
?>Ejemplo #2 php://filter/resource=<flujo a filtrar>
Este parámetro tiene que ubicarse al final de la especificación dephp://filtery tiene que apuntar al flujo que se desea filtrar.
<?php
/* Esto es equivalente a:
readfile("http://www.example.com");
dado que no se especifica ningún filtro */
readfile("php://filter/resource=http://www.example.com");
?>Ejemplo #3 php://filter/read=<lista de filtros a aplicar a la cadena de lectura>
Este parámetro contiene uno o más nombres de filtros separados por el caracter|.
<?php
/* Devolverá el contenido de
www.example.com en mayúsculas */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");
/* Hará lo mismo que el ejemplo de arriba
pero además lo codificará en ROT13 */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>Ejemplo #4 php://filter/write=<lista de filtros a aplicar a la cadena de escritura>
Este parámetro contiene uno o más nombres de filtros separados por el caracter|.
<?php
/* Filtrará el string "Hello World" con
el filtro rot13, y después lo escribirá en
example.txt dentro del directorio actual */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>Ejemplo #5 php://memory y php://temp no son reutilizables
php://memoryyphp://tempno son reutilizabes, esto es, debepués de que los flujos hayan sido cerrados, no hay forma de hacer referencia a ellos de nuevo.
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // no imprime nadazlib://--bzip2://--zip://—Flujos de compresión
zlib:PHP 4.0.4 - PHP 4.2.3 (sólo en sistemas con fopencookie)
compress.zlib://andcompress.bzip2://PHP 4.3.0 y superior
zlib:funciona comogzopen(), solo que usando el flujo, se puede utilizar confread()al igual que con otras funciones del sistema de ficheros. Esto quedó obsoleto en PHP 4.3.0 debido a la ambigüedad que surge con los nombres de fichero que contienen el caracter ':'; en su lugar, debe usarsecompress.zlib://.
compress.zlib://ycompress.bzip2://son equivalentes agzopen()y abzopen()respectivamente, y funcionan incluso en sistemas que no tienen soporte para fopencookie.
Laextensión ZIPregistra la envolturazip:.
data://—Data (RFC 2397)
La envoltura del flujodata:(» RFC 2397) está disponible desde PHP 5.2.0.
Ejemplo #1 Mostrar contenidos de data://
<?php
// muestra "I love PHP"
echofile_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>Ejemplo #2 Obtener el Tipo de Medio
<?php
$fp=fopen('data://text/plain;base64,','r');
$meta=stream_get_meta_data($fp);
// muestra "text/plain"
echo$meta['mediatype'];
?>glob://—Encuentra las rutas que coincidan con el patrón
La envoltura del flujoglob:está disponible desde PHP 5.3.0.
Ejemplo #1 Uso básico
<?php
// Recorrer todos los ficheros *.php del directorio ext/spl/examples/
// y mostrar sus nombres y tamaños
$it= newDirectoryIterator("glob://ext/spl/examples/*.php");
foreach($itas$f) {
printf("%s: %.1FK\n",$f->getFilename(),$f->getSize()/1024);
}
?>tree.php: 1.0K findregex.php: 0.6K findfile.php: 0.7K dba_dump.php: 0.9K nocvsdir.php: 1.1K phar_from_dir.php: 1.0K ini_groups.php: 0.9K directorytree.php: 0.9K dba_array.php: 1.1K class_tree.php: 1.8K
phar://—Archivo PHP
La envoltura de flujophar://está disponible desde PHP 5.3.0. Para consultar una descripción detallada, reviseenvoltura del flujo Phar.
ssh2://—Secure Shell 2
ssh2.shell://ssh2.exec://ssh2.tunnel://ssh2.sftp://ssh2.scp://(PECL)
Nota:Esta envoltura no está habilitada por omisión
Para poder usarse la envolturassh2.*://debe instalarase la extensión» SSH2disponible en» PECL.
Además de permitir hacer un login tradicional en la URI, la envoltura ssh2 también puede reutilizar las conexiones ya abiertas, proporcionando el recurso de conexión en el apartado host de la URL.
Ejemplo #1 Abriendo un flujo a partir de una conexión activa
<?php
$session=ssh2_connect('example.com',22);
ssh2_auth_pubkey_file($session,'username','/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa','secret');
$stream=fopen("ssh2.tunnel://$session/remote.example.com:1234",'r');
?>Ejemplo #2 ¡La variable$sessiondebe permanecer disponible!
Para utilizar la envolturassh2.*://$sessiondebe mantenerse el recurso$sessiondisponible. El código siguiente no tendrá el efecto deseado:
<?php
$session=ssh2_connect('example.com',22);
ssh2_auth_pubkey_file($session,'username','/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa','secret');
$connection_string="ssh2.sftp://$session/";
unset($session);
$stream=fopen($connection_string."path/to/file",'r');
?>unset() cierra la sesión, ya que$connection_stringno contiene una referencia a la variable$session, simplemente una representación de la cadena derivada de ella. Esto también ocurre cuandounset()va implícito porque se sale del ámbito (como dentro de una función).
rar://—RAR
Esta envoltura se compone de una ruta al fichero RAR (relativa o absoluta) codificada como URL, un asterisco opcional (*), un signo de número opcional (#) y un nombre de entrada codificado como URL que también es opcional, tal como se almacena en el fichero. Cuando se especifique un nombre de entrada, será necesario también especificar un signo de número; además, se puede añadir al final del nombre una barra.
Esta envoltura puede abrir tanto ficheros como directorios. Cuando se abre un directorio, el signo asterisco obliga a que los nombres de las entradas del directorio se devuelvan decodificados. Si no se especifica, se devolverán codificadas como URL – esto es así para permitir hacer un uso correcto de la envoltura con determinadas funcionalidades, comoRecursiveDirectoryIteratorcuando se está en presencia de nombres de ficheros que podrían parecen datos codificados como URL.
Si no se proporciona ni un signo de número ni tampoco un número de entrada, se mostrará la raíz del fichero. La diferencia respecto a directorios convencionales es que el flujo no contendrá determinada información, tal como la fecha de modificación, dado que el directorio raíz no se almacena dentro el fichero comprimido en de una entrada individual. Para usar la envoltura conRecursiveDirectoryIteratores necesario que al acceder al raíz se incluya el signo de número en la URL, para que así las URLs de los nodos hijo se puedan construir correctamente.
Nota:Esta envoltura no está habilitada por omisión
Para poder usar la envolturarar://, debe instalarse la extensión» rardisponible en» PECL.
rar://Disponible desde PECL rar 3.0.0
Ejemplo #1 Recorriendo un archivo RAR
<?php
classMyRecDirItextendsRecursiveDirectoryIterator{
functioncurrent() {
returnrawurldecode($this->getSubPathName()) .
(is_dir(parent::current())?" [DIR]":"");
}
}
$f="rar://".rawurlencode(dirname(__FILE__)) .
DIRECTORY_SEPARATOR.'dirs_and_extra_headers.rar#';
$it= newRecursiveTreeIterator(newMyRecDirIt($f));
foreach ($itas$s) {
echo$s,"\n";
}
?>El resultado del ejemplo sería algo similar a:
|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
|-אּ\%2Fempty%2E [DIR]
| \-אּ\%2Fempty%2E\file7.txt
|-אּ\empty [DIR]
|-אּ\file3.txt
|-אּ\file4_אּ.txt
\-אּ\אּ_2 [DIR]
|-אּ\אּ_2\file5.txt
\-אּ\אּ_2\file6_אּ.txt
Ejemplo #2 Abriendo un fichero encriptado (encriptación de cabeceras)
<?php
$stream=fopen("rar://".
rawurlencode(dirname(__FILE__)) .DIRECTORY_SEPARATOR.
'encrypted_headers.rar'.'#encfile1.txt',"r",false,
stream_context_create(
array(
'rar'=>
array(
'open_password'=>'samplepassword'
)
)
)
);
var_dump(stream_get_contents($stream));
/* ni la fecha de creación ni la de último acceso es obligatoria WinRAR,
* por esa razón la mayoría de ficheros no lo tendrán */
var_dump(fstat($stream));
?>El resultado del ejemplo sería algo similar a:
string(34) "Contenido del fichero encriptado 1"
Array
(
[0] => 0
[1] => 0
[2] => 33206
[3] => 1
[4] => 0
[5] => 0
[6] => 0
[7] => 26
[8] => 0
[9] => 1259550052
[10] => 0
[11] => -1
[12] => -1
[dev] => 0
[ino] => 0
[mode] => 33206
[nlink] => 1
[uid] => 0
[gid] => 0
[rdev] => 0
[size] => 26
[atime] => 0
[mtime] => 1259550052
[ctime] => 0
[blksize] => -1
[blocks] => -1
)
ogg://—Flujos de audio
Los ficheros que se abran para lectura usando la envolturaogg://se utilizan como codificaciones de audio comprimido usando el códecOGG/Vorbis. De forma similar, los ficheros abiertos para escritura o para añadir contenido usando la envolturaogg://se escriben como datos de audio comprimidos. Cuando se use la funciónstream_get_meta_data()con un ficheroOGG/Vorbisabierto para lectura, se devolverán diversos detalles del flujo, incluyendo la etiquetavendor, cualquiercommentsque se haya añadido, el número de canaleschannels, elratiode muestreo, y el rango del ratio de codificación descrito por:bitrate_lower,bitrate_upper,bitrate_nominal, ybitrate_window.
ogg://(PECL)
Nota:Esta envoltura no está habilitada por omisión
Para usar la envolturaogg://es necesario instalar la extensión» OGG/Vorbisdisponible en» PECL.
expect://—Flujos de Interacción de Procesos
Los flujos que se hayan abierto con la envolturaexpect://, darán acceso a stdio, stdout y stderr (entrada, salida y errores estándar respectivamente) de los procesos, vía PTY.
Nota:Esta envoltura no está habilitada por omisión
Para poder usar la envolturaexpect://se debe instalar la extensión» Expectdisponible en» PECL.
expect://(PECL)
PHP es un potente lenguaje, y su intérprete, bien como módulo del servidor web o bien como binarioCGI, puede acceder a ficheros, ejecutar comandos o abrir conexiones de red desde el servidor. Estas propiedades hacen que, por omisión, sea inseguro todo lo que se ejecute en un servidor web. PHP está diseñado específicamente para ser un lenguaje más seguro para escribir aplicacionesCGIque Perl o C. Partiendo de un correcto ajuste de opciones de configuración para tiempo de ejecución y en tiempo de compilación, y el uso de prácticas de programación apropiadas, pueden proporcionarle la combinación de libertad y de seguridad que necesita.
Dado que hay muchas vías para ejecutar PHP, existen muchas opciones de configuración para controlar su comportamiento. Al haber una extensa selección de opciones se garantiza poder usar PHP para un gran número de propósitos, pero a la vez significa que existen combinaciones que conllevan una configuración menos segura.
La flexibilidad de configuración de PHP rivaliza igualmente con la flexibilidad de su código. PHP puede ser usado para construir completas aplicaciones de servidor, con toda la potencia de un usuario de consola, o se puede usar sólo desde el lado del servidor implicando un menor riesgo dentro de un entorno controlado. El cómo construir ese entorno, y cómo de seguro es, depende del desarrollador PHP.
Este capítulo comienza con algunos consejos generales de seguridad, explica las diferentes combinaciones de opciones de configuración y las situaciones en que pueden ser útiles, y describe diferentes consideraciones relacionadas con la programación de acuerdo a diferentes niveles de seguridad.
Un sistema completamente seguro es prácticamente un imposible, de modo que el enfoque usado con mayor frecuencia en la profesión de seguridad es uno que busque el balance adecuado entre riesgo y funcionalidad. Si cada variable enviada por un usuario requiriera de dos formas de validación biométrica (como rastreo de retinas y análisis dactilar), usted contaría con un nivel extremadamente alto de confiabilidad. También implicaría que llenar los datos de un formulario razonablemente complejo podría tomar media hora, cosa que podría incentivar a los usuarios a buscar métodos para esquivar los mecanismos de seguridad.
La mejor seguridad con frecuencia es lo suficientemente razonable como para suplir los requerimientos dados sin prevenir que el usuario realice su labor de forma natural, y sin sobrecargar al autor del código con una complejidad excesiva. De hecho, algunos ataques de seguridad son simples recursos que aprovechan las vulnerabilidades de este tipo de seguridad sobrecargada, que tiende a erosionarse con el tiempo.
Una frase que vale la pena recordar: Un sistema es apenas tan bueno como el eslabón más débil de una cadena. Si todas las transacciones son registradas copiosamente basándose en la fecha/hora, ubicación, tipo de transacción, etc. pero la verificación del usuario se realiza únicamente mediante una cookie sencilla, la validez de atar a los usuarios al registro de transacciones es mermada severamente.
Cuando realice pruebas, tenga en mente que no será capaz de probar todas las diferentes posibilidades, incluso para las páginas más simples. Los datos de entrada que usted puede esperar en sus aplicaciones no necesariamente tendrán relación alguna con el tipo de información que podría ingresar un empleado disgustado, un cracker con meses de tiempo entre sus manos, o un gato doméstico caminando sobre el teclado. Es por esto que es mejor observar el código desde una perspectiva lógica, para determinar en dónde podrían introducirse datos inesperados, y luego hacer un seguimiento de cómo esta información es modificada, reducida o amplificada.
Internet está repleto de personas que tratan de crearse fama al romper la seguridad de su código, bloquear su sitio, publicar contenido inapropiado, y por lo demás haciendo que sus días sean más interesantes. No importa si usted administra un sitio pequeño o grande, usted es un objetivo por el simple hecho de estar en línea, por tener un servidor al cual es posible conectarse. Muchas aplicaciones de cracking no hacen distinciones por tamaños, simplemente recorren bloques masivos de direcciones IP en busca de víctimas. Trate de no convertirse en una.
Usar PHP como un binarioCGIes una opción para configuraciones que por alguna razón no desean integrar PHP como un módulo dentro del software de servidor (como Apache), o usarán PHP con diferentes tipos de envoltoriosCGIpara crear entornos seguros chroot y setuid para scripts. Esta configuración usualmente involucra la instalación del binario ejecutable de PHP en el directorio cgi-bin del servidor web. La recomendación» CA-96.11del CERT recomienda que está en contra de colocar cualquiera de los intérpretes dentro de cgi-bin. Aún si el binario de PHP puede ser usado como un intérprete independiente, PHP está diseñado para prevenir los ataques que esta configuración hace posible:
Si su servidor no tiene ningún contenido que no esté restringido por contraseña o control de acceso basado en IP, no hay necesidad de estas opciones de configuración. Si su servidor web no le permite hacer redirecciones, o el servidor no tiene una forma de comunicar al binario de PHP que la petición es una forma segura de petición de redireccionamiento, puede especificar la opción--enable-force-cgi-redirectpara el script de configuración. Usted todavía tiene que asegurarse que sus scripts de PHP no confían en una forma o en otra para llamar el script, ni directamentehttp://my.host/cgi-bin/php/dir/script.phpni por redirecciónhttp://my.host/dir/script.php.
La redirección puede ser configurada en Apache utilizando directivas Action y AddHandler (vea más abajo).
cgi.force_redirectLa directiva de configuracióncgi.force_redirectpreviene a cualquiera que llame a PHP directamente por medio de una URL como estahttp://mi.servidor/cgi-bin/php/directoriosecreto/script.php. En cambio, PHP solamente lo analizará en este modo si éste se ha ido a través de una regla directa del servidor web.
Usualmente la redirección en la configuración de Apache se hace con las siguientes directivas:
Action php-script /cgi-bin/php AddHandler php-script .php
Esta opción ha sido probada solamente con el servidor web Apache, y se basa en que en Apache se configure en una variable de entorno no-estándar de CGIREDIRECT_STATUSpara peticiones de redirección. Si su servidor web no soporta ninguna forma de decirle si la petición es directa o redirigida, usted no puede utilizar esta opción y debe usar una de las otras formas de ejecutar la versión CGI aquí documentadas.
Para incluir contenido activo, como scripts y ejecutables, en los directorios de documentos del servidor web es algunas veces considerado una práctica insegura. Si, por el hecho del algún error de configuración, los scripts no se ejecutan y son mostrados como documentos HTML regulares, esto podría resultar en una fuga de información de propiedad intelectual o de información de seguridad como las contraseñas. Por lo tanto muchos Administradores de Sistemas preferirán configurar otra estructura de directorios para scripts que sean accesibles solamente a través del CGI de PHP, y por lo tanto siempre interpretado y no desplegado como tal.
También si el método para asegurar las peticiones no es redirigido, como se describió en la sección anterior, no está disponible, es necesario configurar un script doc_root que sea diferente de la raíz del documento web.
Usted puede configurar el script de la raíz de documento de PHP en la directiva de configuracióndoc_rooten elfichero de configuración, o puede configurar la variable de entornoPHP_DOCUMENT_ROOT. Si éste es configurado, la versión delCGIde PHP siempre construirá el nombre del fichero para abrir con estedoc_rooty la ruta de información en la petición, de tal forma que pueda estar seguro que ningún script será ejecutado fuera de este directorio (excepto poruser_dirque se encuentra más abajo).
Otra opción utilizable es estauser_dir. Cuando user_dir no está configurado, lo único que controla el fichero abierto esdoc_root. Al abrir una URL comohttp://mi.servidor/~usuario/documento.phpno resulta en la apertura de un fichero bajo el directorio personal de los usuarios, pero si un fichero llamado~usuario/documento.phpdebajo de doc_root (si, un nombre de directorio que inicia con una a tilde [~]).
Si user_dir es configurado, por ejemplopublic_php, una petición comohttp://mi.servidor/~usuario/doc.phpabrirá un fichero llamadodoc.phpbajo el directorio llamadopublic_phpdebajo de el directorio personal del usuario. Si el directorio personal del usuario es/home/usuario, el fichero ejecutado será/home/user/public_php/doc.php.
La expansión deuser_dirsucede sin tomar en cuenta la configuración dedoc_root, así que usted puede controlar el acceso a la raíz de los documentos y el directorio de los usuarios separadamente.
Una opción muy segura es poner el binario analizador de PHP en algún lugar fuera del árbol de ficheros de la web. En/usr/local/bin, por ejemplo. El único inconveniente real con esta opción es que ahora tendrá que poner una línea similar a:
#!/usr/local/bin/php
#!como mecanismo de ejecución de si mismo.Para que PHP maneje la información correctamente dePATH_INFOyPATH_TRANSLATEDcon esta configuración, el analizador de PHP debería ser compilado con la opción de configuración--enable-discard-path.
CuandoPHPes usado como un módulo de Apache, hereda los permisos del usuario de Apache (generalmente los del usuario "nobody"). Este hecho representa varios impactos sobre la seguridad y las autorizaciones. Por ejemplo, si se está usandoPHPpara acceder a una base de datos, a menos que tal base de datos disponga de un control de acceso propio, se tendrá que hacer que la base de datos sea asequible por el usuario "nobody". Esto quiere decir que un script malicioso podría tener acceso y modificar la base de datos, incluso sin un nombre de usuario y contraseña. Es completamente posible que una araña web (bot) pudiera toparse con la página web de administración de una base de datos, y eliminar todo de la base de datos. Una protección ante este tipo de situaciones es mediante el uso del mecanismo de autorización de Apache, o con modelos de acceso de diseño propio usando LDAP, archivos.htaccess, etc. e incluir ese código como parte de los scriptsPHP.
Con frecuencia, una vez la seguridad se ha establecido en un punto en donde el usuario dePHP(en este caso, el usuario de apache) tiene asociada muy poco riesgo, se descubre quePHPse encuentra ahora imposibilitado de escribir archivos en los directorios de los usuarios. O quizás se le haya desprovisto de la capacidad de acceder o modificar bases de datos. Se ha prevenido que pudiera escribir tanto archivos buenos como malos, o que pudiera realizar transacciones buenas o malas en la base de datos.
Un error de seguridad cometido con frecuencia en este punto es darle permisos de administrador (root) a apache, o incrementar las habilidades del usuario de apache de alguna otra forma.
Incrementar los permisos del usuario de Apache hasta el nivel de administrador es extremadamente peligroso y puede comprometer al sistema entero, así que el uso de entornos sudo, chroot, o cualquier otro mecanismo que sea ejecutado como root no debería ser considerado como una opción por aquellos que no son profesionales en seguridad.
Existen otras soluciones más simples. Mediante el uso deopen_basedirse puede controlar y restringir qué directorios pueden ser usados porPHP. También se pueden definir áreas solo-Apache, para restringir todas las actividades basadas en web a archivos que no son de usuarios o del sistema.
Es importante mantener seguro el manejo de sesión HTTP. La seguridad relacionada a la Sesión está descrita enSeguridad de Sesiónen la sección de referenciaMódulo de Sesión.
PHPestá sujeto a la seguridad integrada en la mayoría de sistemas de servidores con respecto a los permisos de archivos y directorios. Esto permite controlar qué archivos en el sistema de archivos se pueden leer. Se debe tener cuidado con los archivos que son legibles para garantizar que son seguros para la lectura por todos los usuarios que tienen acceso al sistema de archivos.
Desde quePHPfue diseñado para permitir el acceso a nivel de usuarios para el sistema de archivos, es perfectamente posible escribir un scriptPHPque le permita leer archivos del sistema como /etc/passwd, modificar sus conexiones de red, enviar trabajos de impresión masiva, etc. Esto tiene algunas implicaciones obvias, es necesario asegurarse que los archivos que se van a leer o escribir son los apropiados.
Considere el siguiente script, donde un usuario indica que quiere borrar un archivo en su directorio home. Esto supone una situación en la que una interfaz web enPHPes usada regularmente para gestionar archivos, por lo que es necesario que el usuario Apache pueda borrar archivos en los directorios home de los usuarios.
Ejemplo #1 Un control pobre puede llevar a ....
<?php
// eliminar un archivo del directorio personal del usuario
$username=$_POST['user_submitted_name'];
$userfile=$_POST['user_submitted_filename'];
$homedir="/home/$username";
unlink("$homedir/$userfile");
echo"El archivo ha sido eliminado!";
?>Ejemplo #2 ... Un ataque al sistema de archivos
<?php
// elimina un archivo desde cualquier lugar en el disco duro al que
// el usuario de PHP tiene acceso. Si PHP tiene acceso de root:
$username=$_POST['user_submitted_name'];// "../etc"
$userfile=$_POST['user_submitted_filename'];// "passwd"
$homedir="/home/$username";// "/home/../etc"
unlink("$homedir/$userfile");// "/home/../etc/passwd"
echo"El archivo ha sido eliminado!";
?>Ejemplo #3 Comprobación más segura del nombre de archivo
<?php
// elimina un archivo del disco duro al que
// el usuario de PHP tiene acceso.
$username=$_SERVER['REMOTE_USER'];// usando un mecanismo de autenticación
$userfile=basename($_POST['user_submitted_filename']);
$homedir="/home/$username";
$filepath="$homedir/$userfile";
if (file_exists($filepath) &&unlink($filepath)) {
$logstring="Se ha eliminado$filepath\n";
} else {
$logstring="No se ha podido eliminar$filepath\n";
}
$fp=fopen("/home/logging/filedelete.log","a");
fwrite($fp,$logstring);
fclose($fp);
echohtmlentities($logstring,ENT_QUOTES);
?>Ejemplo #4 Comprobación más segura del nombre de archivo
<?php
$username=$_SERVER['REMOTE_USER'];// usando un mecanismo de autenticación
$userfile=$_POST['user_submitted_filename'];
$homedir="/home/$username";
$filepath="$homedir/$userfile";
if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD',$userfile)) {
die("nombre de usuario o nombre de archivo incorrecto");
}
//etc...
?>Dependiendo de sus sistema operativo, hay una gran variedad de archivos a los que debe estar atento, esto incluye las entradas de dispositivos (/dev/ o COM1), archivos de configuracion (archivos /etc/ y archivos .ini), las muy conocidas carpetas de almacenamiento (/home/, Mis documentos), etc. Por esta razón, por lo general es más fácil crear una política en donde se prohíba todo excepto lo que expresamente se permite.
ComoPHPutiliza las funciones de C para operaciones relacionadas al sistema de archivos, se podría manejar bytes nulos de manera bastante inesperada. Como un byte nulo denota el fin de una cadena en C, las cadenas que contengan estos no serán consideradas por completo, sino sólo hasta que ocurra un byte nulo. El siguiente ejemplo muestra un código vulnerable que presenta este problema:
Ejemplo #1 Script vulnerable a bytes nulos
<?php
$file=$_GET['file'];// "../../etc/passwd\0"
if (file_exists('/home/wwwrun/'.$file.'.php')) {
// file_exists devolverá true si el archivo /home/wwwrun/../../etc/passwd existe
include'/home/wwwrun/'.$file.'.php';
// el archivo /etc/passwd se incluirá
}
?>Por lo tanto, cualquier cadena que se utiliza en una operación de sistema de archivos siembre deben ser validados correctamente. He aquí una versión mejorada del ejemplo anterior:
Ejemplo #2 Validando correctamente la entrada
<?php
$file=$_GET['file'];
// Lista blanca de valores posibles
switch ($file) {
case'main':
case'foo':
case'bar':
include'/home/wwwrun/include/'.$file.'.php';
break;
default:
include'/home/wwwrun/include/main.php';
}
?>Hoy en día, las bases de datos son componentes esenciales de cualquier aplicación web, permitiendo a los sitios web proveer variedad de contenido dinámico. Puesto que se puede almacenar información muy delicada o secreta en una base de datos, debería considerarse ampliamente proteger las bases de datos.
Para obtener o almacenar cualquier información, es necesario conectarse a la base de datos, enviar una consulta válida, obtener el resultado, y cerrar la conexión. Hoy en día, el lenguaje de consultas más utilizado en esta interacción es el Lenguaje Estructurado de Consultas (SQL, por sus siglas en inglés). Vea como un atacante puederealizar manipulaciones maliciosas con una consulta SQL.
Como es de suponer,PHPno puede proteger una base de datos por sí mismo. Las siguientes secciones tienen como objetivo ser una introducción básica de cómo acceder y manipular bases de datos dentro de scripts dePHP.
Tenga en mente esta sencilla regla: Protección en profundidad. En cuantos más sitios se tomen acciones para aumentar la protección de una base de datos, menor es la probabilidad de que un atacante tenga éxito en exponer o abusar de cualquier información que tenga almacenada. Un buen diseño del esquema de la base de datos y de la aplicación se ocupará de sus mayores temores.
El primer paso es siempre crear una base de datos, a menos que se quiera utilizar una de un tercero. Cuando se crea una base de datos, esta es asignada a un propietario, aquel que ejecutó la sentencia de creación. Usualmente, sólo el propietario (o un superusuario) puede hacer cualquier cosa con los objetos de esa base de datos. Para que otros usuarios puedan utilizarla, se les deben conceder privilegios.
Las aplicaciones nunca deberían conectarse a la base de datos como su propietario o como un superusuario, porque estos usuarios pueden ejecutar cualquier consulta a su antojo; por ejemplo, modificar el esquema (p.ej., eliminar tablas) o borrar su contenido por completo.
Se pueden crear distintos usuarios de una base de datos para cada aspecto de la aplicación con permisos muy limitados a los objetos de dicha base de datos. Solamente deberían otorgarse los privilegios necesarios, evitando así que el mismo usuario pueda interactuar con la base de datos en diferentes casos y uso. Esto significa que si un intruso obtiene acceso a una base de datos utilizando las credenciales de la aplicación, solamente puede efectuar los cambios que la aplicación permita.
Se pueden establecer las conexiones sobre SSL para cifrar las comunicaciones cliente/servidor y aumentar la seguridad, o también emplear ssh para cifrar la conexión de red entre los clientes y el servidor de bases de datos. Si se utiliza algunas de estas opciones, será difícil para un posible atacante la monitorización del tráfico y la obtención de información de la base de datos.
SSL/SSH protege los datos que viajan desde el cliente al servidor: SSL/SSH no protege los datos persistentes almacenados en una base de datos. SSL es un protocolo que protege los datos mientras viajan por el cable.
Una vez que un atacante obtiene acceso directo a una base de datos (eludiendo el servidor web), los datos sensibles almacenados podrían ser divulgados o mal utilizados, a menos que la información esté protegida por la base de datos misma. Cifrar los datos es una buena forma de mitigar esta amenaza, pero muy pocas bases de datos ofrecen este tipo de cifrado de datos.
La forma más sencilla para evitar este problema es crear primero un paquete de cifrado propio y utilizarlo en los scripts dePHP. Hay muchas extensiones dePHPque pueden ser de ayuda para esto, tales comoMcryptyMhash, cubriendo así una amplia variedad de algoritmos de cifrado. El script cifra los datos antes de insertarlos en la base de datos, y los descifra al obtenerlos. Véanse las referencias para ejemplos adicionales del funcionamiento del cifrado.
En caso de datos que deban estar realmente ocultos, si no fuera necesaria su representación real, (es decir, que no sean mostrados), quizás convenga utilizar algoritmos hash. El ejemplo más típico del uso del hash es a la hora de almacenar el hash criptográfico de una contraseña en una base de datos, en lugar de almacenar la contraseña en sí.
En PHP 5.5 o posterior las funciones depasswordproporcionan una forma adecuada de utilizar hash con datos delicados y trabajar con estos hash. En PHP 5.3.7+ se puede utilizar también la biblioteca» password_compat.
password_hash()se emplea para usar un hash con una cadena dada utilizando el algoritmo más fuerte actualmente disponible, mientras quepassword_verify()comprueba si la contraseña dada coincide con el hash almacenado en la base de datos.
Ejemplo #1 Campo de contraseña con hash
<?php
// Almacenar el hash de la contraseña
$consulta=sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($nombre_usuario),
password_hash($contraseña,PASSWORD_DEFAULT));
$resultado=pg_query($conexión,$consulta);
// Consultar si el usuario envió la contraseña correcta
$consulta=sprintf("SELECT pwd FROM users WHERE name='%s';",
pg_escape_string($nombre_usuario));
$fila=pg_fetch_assoc(pg_query($conexión,$consulta));
if ($fila&&password_verify($contraseña,$fila['pwd'])) {
echo'Bienvenido, '.htmlspecialchars($nombre_usuario) .'!';
} else {
echo'La autenticación ha fallado para '.htmlspecialchars($nombre_usuario) .'.';
}
?>En versiones anteriores de PHP esto se puede realizar con la funcióncrypt().
Ejemplo #2 Contraseña con hash utilizandocrypt()
<?php
// Almacenar el hash de la contraseña
// $caracteres_aleatorios se obtuvo, p.ej., utilizando /dev/random
$consulta=sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($nombre_usuario),
pg_escape_string(crypt($contraseña,'$2a$07$'.$caracteres_aleatorios.'$')));
$resultado=pg_query($conexión,$consulta);
// Consultar si el usuario envió la contraseña correcta
$consulta=sprintf("SELECT pwd FROM users WHERE name='%s';",
pg_escape_string($nombre_usuario));
$fila=pg_fetch_assoc(pg_query($conexión,$consulta));
if ($fila&&crypt($contraseña,$fila['pwd']) ==$fila['pwd']) {
echo'Bienvenido, '.htmlspecialchars($nombre_usuario) .'!';
} else {
echo'La autenticación ha fallado para '.htmlspecialchars($nombre_usuario) .'.';
}
?>Muchos desarrolladores web no son conscientes de cómo las consultas SQL pueden ser manipuladas, y asumen que una consulta SQL es una orden fiable. Esto significa que las consultas SQL son capaces de eludir controles de acceso, evitando así las comprobaciones de autenticación y autorización estándar, e incluso algunas veces, que las consultas SQL podrían permitir el acceso a comandos al nivel del sistema operativo del equipo anfitrión.
La inyección directa de comandos SQL es una técnica donde un atacante crea o altera comandos SQL existentes para exponer datos ocultos, sobrescribir los valiosos, o peor aún, ejecutar comandos peligrosos a nivel de sistema en el equipo que hospeda la base de datos. Esto se logra a través de la práctica de tomar la entrada del usuario y combinarla con parámetros estáticos para elaborar una consulta SQL. Los siguientes ejemplos están basados en historias reales, desafortunadamente.
Debido a la falta de validación en la entrada de datos y a la conexión a la base de datos con privilegios de superusuario o de alguien con privilegios para crear usuarios, el atacante podría crear un superusuario en la base de datos.
Ejemplo #1 Dividir el conjunto de resultados en páginas ... y crear superusuarios (PostgreSQL)
<?php
$índice=$argv[0];// ¡Cuidado, no hay validación en la entrada de datos!
$consulta="SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET$índice;";
$resultado=pg_query($conexión,$consulta);
?>0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
select 'crack', usesysid, 't','t','crack'
from pg_shadow where usename='postgres';
--0;es para proveer un índcie válido a la consulta original y así finalizarla.Nota:
Es una técnica común forzar al analizador de SQL a ignorar el resto de la consulta escrita por el desarrollador con
--, lo cual representa un comentario en SQL.
Una forma factible de obtener contraseñas es burlar las páginas de búsqueda de resultados. Lo único que el atacante necesita hacer es ver si hay variables que hayan sido enviadas y sean empleadas en sentencias SQL que no sean manejadas apropiadamente. Estos filtros se pueden establecer comunmente en un formulario anterior para personalizar las cláusulasWHERE, ORDER BY, LIMITyOFFSETen las sentenciasSELECT. Si la base de datos admite el constructorUNION, el atacante podría intentar anteponer una consulta entera a la consulta original para enumerar las contraseñas de una tabla arbitraria. Se recomienda encarecidamente utilizar campos de contraseña encriptadas.
Ejemplo #2 Enumerar artículos ... y algunas contraseñas (cualquier servidor de bases de datos)
<?php
$consulta="SELECT id, name, inserted, size FROM products
WHERE size = '$tamaño'";
$resultado=odbc_exec($conexión,$consulta);
?>SELECTla cual revelará todas las contraseñas:' union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable; --
'y--) fuera asignada a una de las variables utilizadas en$consulta, despertaría a la consulta "monstruo".Las sentecias UPDATE de SQL también son susceptibles a ataques. Estas consultas también están amenazadas por el corte y la anteposición de una consulta completamente nueva. El atacante podría juguetear con la cláusulaSET, aunque en este caso, debe poseer algo de información sobre los esquemas para manipular la consulta con éxito. Esta información puede adquirirse examinando los nombres de las variables del formulario, o sencillamente mediante la fuerza bruta. No hay muchas convenciones de nombres para campos que almacenen contraseñas o nombres de usuarios.
Ejemplo #3 Desde restablecer una contraseña ... hasta obtener más privilegios (cualquier servidor de bases de datos)
<?php
$consulta="UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
?>' or uid like'%admin%a$uidpara cambiar la contraseña del administrador, o simplemente cambiar$pwdajejeje', trusted=100, admin='yespara obtener más privilegios, entonces, la consulta se tornaría:<?php
// $uid: ' or uid like '%admin%
$consulta="UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";
// $pwd: jejeje', trusted=100, admin='yes
$consulta="UPDATE usertable SET pwd='jejeje', trusted=100, admin='yes' WHERE
...;";
?>Un ejemplo turbador de cómo se puede acceder a los comandos a nivel del sistema operativo en algunos equipos anfitriones de bases de datos.
Ejemplo #4 Atacar el sistema operativo que hospeda la base de datos (Servidor MSSQL)
<?php
$consulta="SELECT * FROM products WHERE id LIKE '%$prod%'";
$resultado=mssql_query($consulta);
?>a%' exec master..xp_cmdshell 'net user test testpass /ADD' --a$prod, la$consultaserá:<?php
$consulta="SELECT * FROM products
WHERE id LIKE '%a%'
exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
$resultado=mssql_query($consulta);
?>say el servicio MSSQLSERVER se estuviera ejecutando con los privilegios suficientes, el atacante ahora podría tener una cuenta con la cual acceder a esta máquina.Nota:
Algunos de los ejemplos citados están vinculados a un servidor de bases de datos específico. Esto no significa que un ataque similar sea imposible en otros productos. Su servidor de base de datos también podría ser vulnerable de otra manera.

Pese a que pueda parecer obvio que un atacante debe tener al menos algún conocimiento de arquitecturas de bases de datos para poder realizar un ataque con éxito, la obtención de esta información suele ser muy sencilla. Por ejemplo, cuando la base de datos forma parte de un software de código abierto o disponible públicamente con una instalación predefinida, dicha información se encuentra completamente libre y utilizable. Esta información podría haber sido divulgada en proyectos de código cerrado (incluso si está codificada, ofuscada o compilada), o incluso por el propio código mediante la visualización de mensajes de error. Otros métodos incluyen el uso de nombres frecuentes de tablas y columnas. Por ejemplo, un formulario de inicio de sesión que utiliza una tabla 'usuarios' con los nombres de columna 'id', 'username', y 'password'.
Estos ataques se basan principalmente en explotar el código que no ha sido escrito teniendo en cuenta la seguridad. Nunca se ha de confiar en ningún tipo de entrada, especialmente la que viene del lado del cliente, aún cuando esta venga de un cuadro de selección, un campo oculto o una cookie. El primer ejemplo muestra cómo una inofensiva consulta puede causar desastres.
Si la expresión espera una entrada numérica, considere verificar los datos con la funciónctype_digit(), o silenciosamente cambie su tipo utilizandosettype(), o emplee su representación numérica por medio desprintf().
Ejemplo #5 Una forma más segura de componer una consulta para paginación
<?php
settype($índice,'integer');
$consulta="SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET$índice;";
// Observe %d en el string de formato; el uso de %s podría no tener un resultado significativo
$consulta=sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
$índice);
?>Además, se puede beneficiar del registro de consultas, ya sea dentro de un script o mediante la base de datos en sí misma, si es que lo soporta. Obviamente, llevar un registro no previene los intentos dañinos, aunque puede ser útil para realizar un seguimiento de las aplicación que han sido eludidas. El registro no es útil por sí mismo, sino por la información que contiene. Normalmente cuantos más detalles, mejor.
Con la seguridad de PHP, hay dos formas para reportar errores. Una es en beneficio, para incrementar la seguridad, y la otra es para perjudicar.
Una táctica estándar de ataque conlleva a perfilar un sistema; llenándolo de datos incorrectos, revisando los tipos y contextos de los errores que son devueltos. Esto le permite al atacante recolectar información acerca del servidor, para determinar posibles debilidades. Por ejemplo, si un atacante ha recogido información sobre una página basada en un envío previo, él podría intentar sobrescribir las variables, o modificarlas:
Ejemplo #1 Atacando variables con una página HTML personalizada
<form method="post" action="objetivodelataque?username=badfoo&password=badfoo"> <input type="hidden" name="username" value="badfoo" /> <input type="hidden" name="password" value="badfoo" /> </form>
Los errores de PHP que normalmente son devueltos, pueden ser muy útiles para el desarrollador que está intentando depurar un script, indicando qué cosas, como por ejemplo, qué función o qué fichero de PHP falló, y el número de línea en donde la falla ocurrió. Toda esta es la información que puede ser explotada. Esto no es algo raro para un desarrollador de PHP que utilice las funcionesshow_source(),highlight_string(), ohighlight_file()como una medida de depuración, pero en un sitio en escena, esto puede exponer variables ocultas, sintáxis sin revisar, y otra información peligrosa. Es especialmente peligroso el código en ejecución de fuentes conocidas con manejadores de depuración incluidos, o utilizar técnicas comunes de depuración. Si los atacantes pueden determinar qué técnica en general usted está utilizando, ellos podrían tratar de usar fuerza bruta en una página, enviando varias cadenas comunes de depuración:
Ejemplo #2 Explotando variables comunes de depuración
<form method="post" action="objetivodelataque?errors=Y&showerrors=1&debug=1"> <input type="hidden" name="errors" value="Y" /> <input type="hidden" name="showerrors" value="1" /> <input type="hidden" name="debug" value="1" /> </form>
Sin importar el método de manejo de errores, la capacidad de probar errores en un sistema conlleva a proveer a un atacante con mas información.
Por ejemplo, el estilo común de un error genérico de PHP indica que un sistema ciertamente está ejecutando PHP. Si un atacante está en una página .html, y quiere probar qué motor hay tras de ese servidor (para buscar debilidades en el sistema), lo alimenta con datos erróneos que lo podrían habilitar a que determine que ese sistema fue construido con PHP.
El error de una función puede indicar ya sea, un sistema que puede estar ejecutando un motor específico de base de datos, o dar las pistas de cómo una página web puede estar programada o diseñada. Esto permite una investigación más profunda dentro de los puertos abiertos de la base de datos, o buscar errores específicos o debilidades en una página web. Pasando diferentes porciones de datos erróneos, por ejemplo, un atacante puede determinar el orden de autenticación en un script, (por medio del número de línea de los errores) como también probar exploits que pueden ser utilizados en diferentes ubicaciones del script.
Un error del sistema de archivos o un error general de PHP puede indicar qué permisos tiene el servidor web, así también la estructura y organización de ficheros en el servidor web. El código de error escrito por el desarrollador puede agravar este problema, conllevando a la explotación fácil de la, hasta entonces, información "oculta".
Hay tres grandes soluciones a este problema. La primera consiste en examinar todas las funciones, e intentar arreglar la mayoría de los errores. La segunda es deshabilitar completamente la notificación de errores de el código en ejecución. La tercera es utilizar las funciones de manejo de error propias de PHP para crear su propio manejador de errores. Dependiendo de su política de seguridad, puede ser que encuentre que las tres sean aplicables a su situación.
Una forma de detectar este problema por adelantado es hacer uso de la función propia de PHPerror_reporting(), para ayudarle a asegurar su código y encontrar el uso de variables que podrían ser peligrosas. Al probar su código, antes de distribuirlo, conE_ALL, usted puede encontrar rapidamente áreas donde sus variables pueden ser abiertas para envenenamiento o modificación en otras maneras. Una vez usted está listo para distribuirlo, debería deshabilitar completamente el reporte de errores poniendo el valor deerror_reporting()a 0, o apagar el visor de errores utilizando la opcióndisplay_errorsdel ficherophp.inipara aislar su código de ataques. Si decide hacer esto último, también debería definir la ruta de acceso a su archivo de registros utilizando la directivaerror_log, y ponerlog_errorsen "on".
Ejemplo #3 Buscando variables peligrosas con E_ALL
<?php
if ($usuario) {// No se ha inicializado o revisado antes de utilizar
$permitir_acceso=1;
}
if ($permitir_acceso==1) {// Si la prueba anterior falla, los que no estén inicializados o comprobados antes de utilizar, tendrán acceso
readfile("/ruta/hacia/datos/altamente/sensibles/index.html");
}
?>Las mayores debilidades de muchos programasPHPno son inherentes al lenguaje mismo, sino simplemente un problema generado cuando se escribe código sin pensar en la seguridad. Por esta razón, usted debería tomarse siempre el tiempo para considerar las implicaciones de cada pedazo de código, para averiguar el posible peligro involucrado cuando una variable inesperada es enviada.
Ejemplo #1 Uso Peligroso de Variables
<?php
// eliminar un archivo del directorio personal del usuario .. ¿o
// quizás de alguien más?
unlink($variable_malvada);
// Imprimir el registro del acceso... ¿o quizás una entrada de /etc/passwd?
fwrite($desc_archivo,$variable_malvada);
// Ejecutar algo trivial.. ¿o rm -rf *?
system($variable_malvada);
exec($variable_malvada);
?>Usted debería examinar siempre, y cuidadosamente su código para asegurarse de que cualquier variable siendo enviada desde un navegador web sea chequeada apropiadamente, y preguntarse a sí mismo:
Al preguntarse adecuadamente estas preguntas mientras escribe su script, en lugar de hacerlo posteriormente, usted previene una desafortunada re-implementación del programa cuando desee incrementar el nivel de seguridad. Al comenzar con esta mentalidad, no garantizará la seguridad de su sistema, pero puede ayudar a mejorarla.
Puede que también desee considerar la deshabilitación de register_globals, magic_quotes, u otros parámetros convenientes que pueden causar confusión sobre la validez, fuente o valor de una determinada variable. Trabajar conPHPen modo error_reporting(E_ALL) también puede ayudarle a advertir variables que están siendo usadas antes de ser chequeadas o inicializadas (de modo que puede prevenir que datos inusuales produzcan operaciones inadvertidas).
En general, la seguridad por ocultación es una de las formas más débiles de seguridad. Aunque en algunos casos, es aconsejable cada pequeño elemento extra de seguridad.
Unas cuantas técnicas simples pueden ayudar a ocultarPHP, posiblemente retrasando a un atacante que esté tratando de descubrir debilidades en el sistema. Al establecer expose_php aoffen el ficherophp.ini, se reduce la cantidad de información disponible.
Otra táctica es configurar servidores web como Apache para interpretar diferentes tipos de ficheros por medio dePHP, ya sea con una directiva de.htaccesso en el propio fichero de configuración de Apache. Así se pueden utilizar extensiones de ficheros engañosas:
Ejemplo #1 Ocultando PHP como si fuera otro lenguaje
# Hacer que el código de PHP parezca otro tipo de código AddType application/x-httpd-php .asp .py .pl
Ejemplo #2 Utilizar tipos desconocidos para extensiones de PHP
# Hacer que el código de PHP parezca de tipo desconocido AddType application/x-httpd-php .bop .foo .133t
Ejemplo #3 Utilizar tiposHTMLpara extensiones de PHP
# Hacer que el código de PHP parezca HTML AddType application/x-httpd-php .htm .html
PHP, como cualquier otro sistema de tamaño considerable, está bajo constante escrutinio y mejoramiento. Cada nueva versión incluye con frecuencia cambios mayores y menores para mejorar la seguridad y reparar cualquier fallo, problemas de configuración, y otros asuntos que puedan afectar la seguridad y estabilidad global del sistema.
Como cualquier lenguaje y programa de script a nivel de sistema, la mejor estrategia es actualizar con frecuencia y mantenerse alerta sobre las últimas versiones y sus cambios.
Con la funciónheader()se puede enviar un mensaje de"Autenticación requerida"al navegador del cliente para mostrar una ventana emergente donde introducir un usuario y una contraseña. Una vez introducidos estos datos, el URL que contiene el script de PHP será invocado de nuevo con lasvariables predefinidasPHP_AUTH_USER,PHP_AUTH_PWyAUTH_TYPEestablecidas al nombre de usuario, contraseña y tipo de autenticación, respectivamente. Estas variables se encuentran en el array$_SERVER. Se admiten ambos métodos de autenticación, 'Basic' y 'Digest' (desde PHP 5.1.0). Véase la funciónheader()para más información.
Un fragmento de un script de ejemplo que forzaría la autenticación en una página es el siguiente:
Ejemplo #1 Ejemplo de autenticación HTTP 'Basic'
<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
header('WWW-Authenticate: Basic realm="Mi dominio"');
header('HTTP/1.0 401 Unauthorized');
echo'Texto a enviar si el usuario pulsa el botón Cancelar';
exit;
} else {
echo"<p>Hola{$_SERVER['PHP_AUTH_USER']}.</p>";
echo"<p>Introdujo{$_SERVER['PHP_AUTH_PW']}como su contraseña.</p>";
}
?>Ejemplo #2 Ejemplo de autenticación HTTP 'Digest'
Este ejemplo muestra cómo implementar un sencillo script de autenticación HTTP 'Digest'. Para más información lea el» RFC 2617.
<?php
$dominio='Area restringida';
// usuario => contraseña
$usuarios= array('admin'=>'micontraseña','invitado'=>'invitado');
if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Digest realm="'.$dominio.
'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($dominio).'"');
die('Texto a enviar si el usuario pulsa el botón Cancelar');
}
// Analizar la variable PHP_AUTH_DIGEST
if (!($datos=analizar_http_digest($_SERVER['PHP_AUTH_DIGEST'])) ||
!isset($usuarios[$datos['username']]))
die('Credenciales incorrectas');
// Generar una respuesta válida
$A1=md5($datos['username'] .':'.$dominio.':'.$usuarios[$datos['username']]);
$A2=md5($_SERVER['REQUEST_METHOD'].':'.$datos['uri']);
$respuesta_válida=md5($A1.':'.$datos['nonce'].':'.$datos['nc'].':'.$datos['cnonce'].':'.$datos['qop'].':'.$A2);
if ($datos['response'] !=$respuesta_válida)
die('Credenciales incorrectas');
// Todo bien, usuario y contraseña válidos
echo'Se ha identificado como: '.$datos['username'];
// Función para analizar la cabecera de autenticación HTTP
functionanalizar_http_digest($txt)
{
// Protección contra datos ausentes
$partes_necesarias= array('nonce'=>1,'nc'=>1,'cnonce'=>1,'qop'=>1,'username'=>1,'uri'=>1,'response'=>1);
$datos= array();
$claves=implode('|',array_keys($partes_necesarias));
preg_match_all('@('.$claves.')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@',$txt,$coincidencias,PREG_SET_ORDER);
foreach ($coincidenciasas$c) {
$datos[$c[1]] =$c[3] ?$c[3] :$c[4];
unset($partes_necesarias[$c[1]]);
}
return$partes_necesarias?false:$datos;
}
?>Nota:Sobre la compatibilidad
Hay que tener cuidado al codificar las líneas de cabeceras HTTP. Para garantizar la mayor compatibilidad con todos los clientes, la palabra 'Basic' debe escribirse con 'B' mayúscula, la cadena del dominio debe estar entre comillas dobles (no simples), y debería haber exactamente un espacio precediendo al código401de la línea de la cabeceraHTTP/1.0 401. Los parámetros de autenticación deben estar separados por comas, como se vió en el ejemplo de 'Digest' anterior.
En lugar de imprimir simplementePHP_AUTH_USERyPHP_AUTH_PWcomo se hizo en el ejemplo anterior, podría ser conveniente validar el usuario y la contraseña, tal vez enviando una consulta a una base de datos o buscando el usuario en un fichero dbm.
Cuidado con los navegadores Internet Explorer defectuosos. Parecen ser muy quisquillosos con el orden de las cabeceras. Por ahora, parece ser que el truco está en enviar la cabeceraWWW-Authenticateantes que la cabeceraHTTP/1.0 401.
Para prevenir que alguien escriba un script que revele la contraseña de una página que se autenticó con un mecanismo externo tradicional, las variables PHP_AUTH no se establecerán si la autenticación externa está habilitada para esa página en particular. Independientemente, se puede emplearREMOTE_USERpara identificar al usuario autenticado externamente. De este modo, se podrá usar$_SERVER['REMOTE_USER'].
Nota:Sobre la configuración
PHP utiliza la presencia de una directiva
AuthTypepara determinar si una autenticación externa está en uso.
Observe, sin embargo, que lo anterior no impide que alguien que controle un URL no autenticado pueda robar contraseñas de URL autenticados en el mismo servidor.
Tanto Netscape Navigator como Internet Explorer borran la caché de autenticación de la ventana del navegador local para el dominio al recibr una respuesta 401 del servidor. Esto, en efecto, puede hacer que se cierre la sesión de un usuario, obligándolo a reintroducir su nombre de usuario y contraseña. Algunos utilizan esto para inicios de sesión «expiradas» o proveer un botón de «Cerrar sesión».
Ejemplo #3 Ejemplo de autenticación HTTP forzando un nuevo usuario/contraseña
<?php
functionautenticar() {
header('WWW-Authenticate: Basic realm="Sistema de autenticación de prueba"');
header('HTTP/1.0 401 Unauthorized');
echo"Debe introducir un ID y contraseña de identificación válidos para acceder a este recurso\n";
exit;
}
if (!isset($_SERVER['PHP_AUTH_USER']) ||
($_POST['VistoAntes'] ==1&&$_POST['UsuarioAntiguo'] ==$_SERVER['PHP_AUTH_USER'])) {
autenticar();
} else {
echo"<p>Bienvenido: ".htmlspecialchars($_SERVER['PHP_AUTH_USER']) ."<br />";
echo"Antiguo: ".htmlspecialchars($_REQUEST['UsuarioAntiguo']);
echo"<form action='' method='post'>\n";
echo"<input type='hidden' name='VistoAntes' value='1' />\n";
echo"<input type='hidden' name='UsuarioAntiguo' value=\"".htmlspecialchars($_SERVER['PHP_AUTH_USER']) ."\" />\n";
echo"<input type='submit' value='Reautenticar' />\n";
echo"</form></p>\n";
}
?>El estándar de autenticaciónHTTP Basicno requiere este funcionamiento, por lo que no se debería depender de ello. Las pruebas conLynxhan mostrado queLynxno limpia las credenciales de autenticación con una respuesta 401 del servidor, por lo que al presionar «atrás» y luego «adelante» abrirá el recurso nuevamente mientras los requisitos de credenciales no hayan cambiado. Sin embargo, el usuario puede pulsar la tecla'_'para limpiar su información de autenticación.
Para que la Autenticación HTTP funcione en un servidor IIS con la versión CGI de PHP, se debe editar la configuracion de "Seguridad de directorios" de IIS: hacer clic en "Editar" y solo marcar "Acceso anónimo"; todos los demas campos deberían estar sin marcar.
Nota:Sobre IIS:
Para que funcione la Autenticación HTTP con IIS, la directiva de PHPcgi.rfc2616_headersdebe establecerse a0(el valor predeterminado).
El soporte para sesiones en PHP consiste en una manera de preservar ciertos datos a través de accesos posteriores, lo que permite crear aplicaciones más personalizadas y mejorar el atractivo de un sitio web. Toda la información está en la secciónReferencia de sesiones.
» XFormsdefine una variante de los formularios web tradicionales que permite emplearla en una gran variedad de plataformas y navegadores o incluso en medios no tradicionales como los documentos PDF.
La primera diferencia principal en XForms es la forma de enviar el formulario al cliente.» XForms for HTML Authorscontiene una descripción detallada de cómo crear XForms; para el propósito de este tutorial únicamente veremos un ejemplo simple.
Ejemplo #1 Un formulario simple de búsqueda con XForms
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Búsqueda</h:title>
<model>
<submission action="http://example.com/search"
method="post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Buscar</label></input>
<submit submission="s"><label>Ir</label></submit>
</h:p>
</h:body>
</h:html>El formulario anterior muestra una caja de entrada de texto (llamadaq), y un botón de envío. Al presionar este botón, el formulario se envía a la página indicada poraction.
Aquí es donde comienzan a verse las diferencias desde el punto de vista de la aplicación web. En un formulario normal de HTML, los datos serían enviados comoapplication/x-www-form-urlencoded; en el mundo de XForms, esta información es enviada como datos formateados enXML.
Si se elige trabajar con XForms, sería conveniente que los datos se obtuvieran comoXML. En tal caso, se puede examinar$HTTP_RAW_POST_DATApara encontrar el documentoXMLgenerado por el navegador, el cual se puede pasar al motor deXSLTo al analizador de documentos favorito.
Si no se está interesado en formatear los datos y solo se desea que se carguen en la variable$_POSTtradicional, se puede instruir al navegador del cliente para enviarlos comoapplication/x-www-form-urlencodedcambiando el atributomethodaurlencoded-post.
Ejemplo #2 Empleo de un Xform para rellenar$_POST
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Búsqueda</h:title>
<model>
<submission action="http://example.com/search"
method="urlencoded-post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Buscar</label></input>
<submit submission="s"><label>Ir</label></submit>
</h:p>
</h:body>
</h:html>Nota:En el momento de escribir esto, muchos navegadores no admiten XForms. Compruebe la versión de su navegador si los ejemplos anteriores fallan.
Esta característica permite la subida de ficheros de texto y binarios. Con la autenticación de PHP y las funciones de manipulación de ficheros se tiene control completo sobre quién está autorizado a realizar una subida y qué hay que hacer con el fichero una vez subido.
PHP es capaz de recibir subidas de ficheros de cualquier navegador compatible con el RFC-1867.
Nota:Nota sobre configuraciones relacionadas
Véase también las directivasfile_uploads,upload_max_filesize,upload_tmp_dir,post_max_sizeymax_input_timedephp.ini
PHP también admite el método PUT para subir ficheros tal y como lo utilizan los clientesNetscape ComposeryAmayadel W3C. Véase elSoporte para el método PUTpara más detalles.
Ejemplo #1 Formulario para la subida de ficheros
Se puede construir una página de subida de ficheros creando un formulario especial parecido a este:
<!-- El tipo de codificación de datos, enctype, DEBE especificarse como sigue -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
<!-- MAX_FILE_SIZE debe preceder al campo de entrada del fichero -->
<input type="hidden" name="MAX_FILE_SIZE" value="30000" />
<!-- El nombre del elemento de entrada determina el nombre en el array $_FILES -->
Enviar este fichero: <input name="fichero_usuario" type="file" />
<input type="submit" value="Enviar fichero" />
</form>El__URL__del ejemplo anterior se debe sustituir y debe apuntar a un fichero de PHP.
El campo ocultoMAX_FILE_SIZE(medido en bytes) debe preceder al campo de entrada del fichero, siendo su valor el tamaño de fichero máximo aceptado por PHP. Se debe utilizar siempre este elemento del formulario, ya que evita a los usuarios la molestia de esperar a que un fichero grande sea transferido sólo para descubrir que falló la transferencia porque era demasiado grande. Hay que tener en cuenta que engañar a esta configuración en el lado del navegador es muy fácil; nunca dependa de que los ficheros que tengan un tamaño mayor sean bloqueados por esta característica. Es simplemente una característica conventiene para los usuarios en el lado cliente de la aplicación. No obstante, la configuración de PHP (en el lado del servidor) para un tamaño máximo no puede ser engañada.
Nota:
Asegúrese de que el formulario de subida de ficheros tiene el atributo
enctype="multipart/form-data"o de lo contrario la subida de ficheros no funcionará.
El array global$_FILEScontendrá toda la información de los los ficheros subidos. Su contenido en el formulario del ejemplo es el siguiente. Observe que se asume el empleo del nombrefichero_usuariopara el fichero subido, tal como se utiliza en el script de ejemplo anterior. Este puede ser cualquier nombre.
El nombre original del fichero en la máquina del cliente.
El tipo MIME del fichero, si el navegador proporcionó esta información. Un ejemplo sería"image/gif". Este tipo MIME, sin embargo, no se comprueba en el lado de PHP y por lo tanto no se garantiza su valor.
El tamaño, en bytes, del fichero subido.
El nombre temporal del fichero en el cual se almacena el fichero subido en el servidor.
Elcódigo de errorasociado a esta subida.
Por omisión, los ficheros se almacenan en el directorio temporal predeterminado del servidor, a menos que se haya indicado otra ubicaicón con la directivaupload_tmp_direnphp.ini. Se puede cambiar el directorio predeterminado del servidor estableciendo la variable de entornoTMPDIRen el entorno en que se ejecuta PHP. Configurarlo usandoputenv()desde un script de PHP no funcionará. Esta variable de entorno también se puede utilizar para asegurarse de que las demás operaciones están trabajando sobre los ficheros subidos.
Ejemplo #2 Validación de la subida de ficheros
Véanse también las entradas de las funcionesis_uploaded_file()ymove_uploaded_file()para más información. El siguiente ejemplo procesará la subida de fichero desde un formulario.
<?php
$dir_subida='/var/www/uploads/';
$fichero_subido=$dir_subida.basename($_FILES['fichero_usuario']['name']);
echo'<pre>';
if (move_uploaded_file($_FILES['fichero_usuario']['tmp_name'],$fichero_subido)) {
echo"El fichero es válido y se subió con éxito.\n";
} else {
echo"¡Posible ataque de subida de ficheros!\n";
}
echo'Más información de depuración:';
print_r($_FILES);
print"</pre>";
?>El script de PHP que recibe el fichero subido debería implementar cualquier lógica necesaria para determinar qué se debe hacer con el fichero subido. Se puede, por ejemplo, utilizar la variable$_FILES['fichero_usuario']['size']para descartar cualquier fichero que sea demasiado pequeño o demasiado grande. Se podría utilizar la variable$_FILES['fichero_usuario']['type']para descartar cualquier fichero que no corresponda con un cierto criterio de tipo, aunque esto se debe emplear solo como la primera de una serie de comprobaciones debido a que este valor está completamente bajo el control del cliente y no se comprueba en el lado de PHP. También se puede usar$_FILES['fichero_usuario']['error']y planear la lógica de acuerdo con loscódigos de error. Cualquiera que sea la lógica, se debería borrar el fichero del directorio temporal o moverlo a otra ubicación.
Si no se selecciona ningún fichero en el formulario para realizar la subida, PHP devolverá$_FILES['fichero_usuario']['size']como 0, y$_FILES['fichero_usuario']['tmp_name']como ninguno.
El fichero será borrado del directorio temporal al final de la solicitud si este no ha sido movido o renombrado.
Ejemplo #3 Subir un array de ficheros
PHP admite lafuncionalidad de array en HTMLincluso con ficheros.
<form action="" method="post" enctype="multipart/form-data"> <p>Imágenes: <input type="file" name="imágenes[]" /> <input type="file" name="imágenes[]" /> <input type="file" name="imágenes[]" /> <input type="submit" value="Enviar" /> </p> </form>
<?php
foreach ($_FILES["imágenes"]["error"] as$clave=>$error) {
if ($error==UPLOAD_ERR_OK) {
$nombre_tmp=$_FILES["imágenes"]["tmp_name"][$clave];
// basename() puede evitar ataques de denegació del sistema de ficheros;
// podría ser apropiado más validación/saneamiento del nombre de fichero
$nombre=basename($_FILES["imágenes"]["name"][$clave]);
move_uploaded_file($nombre_tmp,"datos/$nombre");
}
}
?>Se puede implementar una barra de progreso de subida de ficheros con elProgreso de subida en sesiones.
PHP devuelve un código de error apropiado junto con el array de ficheros. El código de error se puede encontrar en el segmentoerrordel array de ficheros que PHP crea durante la subida de ficheros. En otras palabras, el error puede encontrarse en$_FILES['fichero_usuario']['error'].
UPLOAD_ERR_OKValor: 0; No hay error, fichero subido con éxito.
UPLOAD_ERR_INI_SIZEValor: 1; El fichero subido excede la directivaupload_max_filesizedephp.ini.
UPLOAD_ERR_FORM_SIZEValor: 2; El fichero subido excede la directivaMAX_FILE_SIZEespecificada en el formulario HTML.
UPLOAD_ERR_PARTIALValor: 3; El fichero fue sólo parcialmente subido.
UPLOAD_ERR_NO_FILEValor: 4; No se subió ningún fichero.
UPLOAD_ERR_NO_TMP_DIRValor: 6; Falta la carpeta temporal.
UPLOAD_ERR_CANT_WRITEValor: 7; No se pudo escribir el fichero en el disco.
UPLOAD_ERR_EXTENSIONValor: 8; Una extensión de PHP detuvo la subida de ficheros. PHP no proporciona una forma de determinar la extensión que causó la parada de la subida de ficheros; el examen de la lista de extensiones cargadas conphpinfo()puede ayudar.
El elementoMAX_FILE_SIZEno puede especificar un tamaño de fichero mayor que el establecido en la directivaupload_max_filesizedel ficherophp.ini. Por defecto es 2 megabytes.
Si hay un límite de memoria habilitado, podría ser necesario un valor dememory_limitmás grande. Asegúrese de establecer un valor dememory_limitlo suficientemente grande.
Si el valor demax_execution_timees demasiado pequeño, la ejecución del script podría exceder este valor. Asegúrese de establecer un valor demax_execution_timelo suficientemente grande.
Nota:max_execution_timesolo afecta al tiempo de ejecución del propio script. Todo tiempo empleado en actividades externas a la ejecución del script, tales como las llamadas al sistema consystem(), la funciónsleep(), las consultas a base de datos, el tiempo que tarda el proceso de subida de ficheros, etc., no se incluye para determinar el tiempo máximo que el script ha estado en ejecución.
max_input_timeestablece el tiempo máximo, en segundos, que al script se le permite recibir información; esto incluye la subida de ficheros. Para ficheros grandes o varios ficheros, o usuarios con conexiones más lentas, podría excederse el valor predeterminado de60 segundos.
Si el valor depost_max_sizese establece demasiado pequeño, los ficheros grandes no podrán ser subidos. Asegúrese de establecerpost_max_sizelo suficientemente grande.
El ajuste de configuraciónmax_file_uploadscontrola el número máximo de ficheros que se pueden subir en una petición. Si se suben más ficheros que el límite establecido,$_FILESparará de procesar ficheros una vez se alcance este límite. Por ejemplo, simax_file_uploadsse establece a10,$_FILESnunca contendrá más de 10 elementos.
No validar sobre qué fichero se opera podría significar que los usuarios pueden acceder a información delicada de otros directorios.
Por favor, observe que elCERN httpdparece quitar todo lo que empieza con primer espacio en blanco en la cabecera de tipo de contenido MIME que recibe desde el cliente. Mientras este sea el caso, elCERN httpdno tendrá soporte para la funcionalidad de subida de ficheros.
Debido a la gran cantidad de estilos de listados de directorios, no podemos garantizar que los ficheros con nombres exóticos (como el que contiene espacios en blanco) se manejen adecuadamente.
Los desarrolladores no deben mezclar los camposinputnormales con los de subida de ficheros en la misma variable de formulario (mediante un nombre deinputcomofoo[]).
Se pueden subir varios ficheros utilizando diferentesnamepara losinput.
También es posible subir varios ficheros simultáneamente y tener la información organizada automáticamente en arrays. Para ello es necesario utilizar la misma sintaxis de presentación de array en el formulario HTML, tal como se hace con 'selects' y 'checkboxes' múltiples:
Ejemplo #1 Subida de varios ficheros
<form action="file-upload.php" method="post" enctype="multipart/form-data"> Enviar estos ficheros:<br /> <input name="fichero_usuario[]" type="file" /><br /> <input name="fichero_usuario[]" type="file" /><br /> <input type="submit" value="Enviar ficheros" /> </form>
Cuando se envía el formulario de arriba, se inicializarán los arrays$_FILES['fichero_usuario'],$_FILES['fichero_usuario']['name']y$_FILES['fichero_usuario']['size']serán inicializados.
Por ejemplo, suponga que se envían los nombres de fichero/home/test/review.htmly/home/test/xwp.out. En este caso,$_FILES['fichero_usuario']['name'][0]contendría el valorreview.html, y$_FILES['fichero_usuario']['name'][1]contendría el valorxwp.out. De manera similar,$_FILES['fichero_usuario']['size'][0]contendría el tamaño del ficheroreview.html, y así sucesivamente.
También se establecen$_FILES['fichero_usuario']['name'][0],$_FILES['fichero_usuario']['tmp_name'][0],$_FILES['fichero_usuario']['size'][0], y$_FILES['fichero_usuario']['type'][0].
El ajuste de configuraciónmax_file_uploadsactúa como límite del número de ficheros que se pueden subir en una petición. Es necesario asegurarse de que el formulario no intente subir más ficheros que este límite en una petición.
PHP ofrece soporte para el método PUT de HTTP utilizado por algunos clientes para almacenar ficheros en un servidor. Las peticiones PUT son mucho más simples que una subida de ficheros mediante peticiones POST. Se ven algo como esto:
PUT /ruta/nombrefichero.html HTTP/1.1
Esto normalmente significaría que el cliente remoto quiere guardar el contenido que le sigue como:/ruta/nombrefichero.htmlen el árbol web. Obviamente, no es una buena idea que Apache o PHP permitan a todo el mundo sobrescribir automáticamente cualquier fichero del árbol web. Por tanto, para manejar tales peticiones se debe primero indicar al servidor web que cierto script de PHP maneje la petición. En Apache, esto se hace con la directivaScript. Esta se puede colocar casi en cualquier parte del fichero de configuración de Apache. Un lugar común es dentro de un bloque<Directory>o tal vez dentro de un bloque<VirtualHost>. Una línea como ésta resolvería el problema:
Script PUT /put.php
Esto le indica a Apache que envíe todas las peticiones PUT para los URI que coincidan con el contexto en el cual se pone esta línea en el scriptput.php. Se asume, por supuesto, que se tiene habilitado PHP para la extensión.phpy que PHP está activo. El recurso de destino para todas las peiticiones PUT a este script tiene que ser el propio script, no el nombre de fichero que debería tener el fichero subido.
Entonces, con PHP se haría algo como lo siguiente en el fichero put.php. Se copiaría el contenido del fichero subido al ficheromificheroput.exten el servidor. Podría ser conveniente realizar algunas comprobaciones y/o autenticar al usuario antes de realizar esta copia del fichero.
Ejemplo #1 Guardar ficheros PUT de HTTP
<?php
/* Los datos de PUT vienen en el flujo de entrada estándar */
$datosPUT=fopen("php://input","r");
/* Abrir un fichero para escritura */
$fp=fopen("mificheroput.ext","w");
/* Leer 1 KB de datos cada vez
y escribir en el fichero */
while ($datos=fread($datosPUT,1024))
fwrite($fp,$datos);
/* Cerrar los flujos */
fclose($fp);
fclose($datosPUT);
?>Siempre queallow_url_fopenesté habilitado enphp.ini, se pueden usar los URL deHTTPyFTPcon la mayoría de las funciones que toman un nombre de fichero como parámetro. Además, los URL se pueden emplear con las sentenciasinclude,include_once,requireyrequire_once(desde PHP 5.2.0,allow_url_includedebe estar habilitado para ello). VéanseProtocolos y Envolturas soportadospara más información sobre los protocolos admitidos por PHP.
Por ejemplo, se puede emplear para abrir un fichero en un servidor web remoto, analizar la salida de los datos deseados, y usar dichos datos en una consulta a una base de datos, o simplemente para mostrarlos en un estilo que haga juego con el del sitio web.
Ejemplo #1 Obtener el título de una página remota
<?php
$fichero=fopen("http://www.example.com/","r");
if (!$fichero) {
echo"<p>Imposible abrir el fichero remoto.\n";
exit;
}
while (!feof($fichero)) {
$línea=fgets($fichero,1024);
/* Esto solo funciona si el título y sus etiquetas están en una línea */
if (preg_match("@\<title\>(.*)\</title\>@i",$línea,$salida)) {
$título=$salida[1];
break;
}
}
fclose($fichero);
?>También se puede escribir en ficheros de un servidor FTP (siempre que se esté conectado como un usuario con los permisos de acceso correctos). Con este método solamente se pueden crear ficheros nuevos. Si se intenta sobreescribir un fichero que ya existe, la llamada a la funciónfopen()fallará.
Para conectarse como un usuario distinto a 'anonymous', es necesario especificar el nombre de usuario (y posiblemente la contraseña) dentro del URL, tal como 'ftp://usuario:contraseña@ftp.example.com/ruta/al/fichero'. (Se puede utilizar la misma sintaxis para acceder a ficheros medianteHTTPcuando se requiera autenticación básica).
Ejemplo #2 Almacenar datos en un servidor remoto
<?php
$fichero=fopen("ftp://ftp.example.com/incoming/outputfile","w");
if (!$fichero) {
echo"<p>Imposible abrir el fichero remoto para escritura.\n";
exit;
}
/* Escribir los datos aqui. */
fwrite($fichero,$_SERVER['HTTP_USER_AGENT'] ."\n");
fclose($fichero);
?>Nota:
Con el ejemplo anterior, se podría tener la idea de que se puede emplear esta técnica para escribir un fichero de registro remoto. Desafortunadamente esto no funcionaría porque la llamada a la funciónfopen()fallará si el fichero remoto ya existe. Para realizar registros distribuidos como ese, debería echar un vistazo asyslog().
Internamente, en PHP se mantiene un estado de conexión. Hay 4 posibles estados:
Cuando un script de PHP está ejecutándose normalmente está activo el estado NORMAL (normal). Si el cliente remoto se desconecta, se activa el indicador de estado ABORTED (abortada). Un cliente remoto se desconecta normalmente porque presiona su botón STOP. Si se alcanza el tiempo límite impuesto por PHP (véaseset_time_limit()), se activa el indicador de estado TIMEOUT (expirada).
Se puede decidir si se desea que un cliente que se desconecte ocasione que se aborte el script. Algunas veces es útil que los scripts se ejecuten hasta su finalización, incluso si ya no hay un navegador remoto recibiendo la salida. Sin embargo, el comportamiento predeterminado es que el script sea abortado cuando el cliente remoto se desconecte. Este comportamiento puede ser establecido a través de la directiva ignore_user_abort dephp.ini, así como a través de la directiva correspondiente de Apachephp_value ignore_user_abortdehttpd.conf, o con la funciónignore_user_abort(). Si se decide no indicarle a PHP que ignore que el usuario aborte y el usuario aborta, el script finalizará. La única excepción es si se tiene registrada una función de apagado conregister_shutdown_function(). Con una función de apagado, cuando el usuario remoto activa el botón STOP, la próxima vez que el script intente mostrar algo, PHP detectará que la conexión fue abortada, llamando así a la función de apagado. Esta función de apagado también se invoca al final del script cuando finaliza normalmente, así que para hacer algo diferente en caso de que un cliente se desconecte, se puede emplear la funciónconnection_aborted(). Esta función devolverátruesi la conexión fue abortada.
El script puede ser finalizado también por el temporizador de script incorporado. El tiempo predeterminado es de 30 segundos. Se puede cambiar con la directivamax_execution_timedephp.inio la correspondiente de Apachephp_value max_execution_timedehttpd.conf, así como con la funciónset_time_limit(). Cuando el temporizador expira, el script se abortará y, como el caso del cliente anterior que se desconectó, si la función de apagado ha sido registrada, será llamada. Dentro de esta función de apagado se puede comprobar si el tiempo de espera causó la llamada a la función de apagado invocando a la funciónconnection_status(). Esta función devolverá 2 si el tiempo de espera causó la llamada a la función de apagado.
Una cosa a observar es que los estados ABORTED y TIMEOUT pueden estar activados al mismo tiempo. Esto es posible si se le indica a PHP que ignore los abortos que ocasione el usuario. PHP notará de hecho que un usuario podría haber roto la conexión, pero el script se mantendrá ejecutándose. Si entonces se alcanza el límite de tiempo, será abortado y la función de apagado, si la hubiera, será llamada. En este punto se encontrará queconnection_status()devuelve 3.
Las conexiones persistentes son enlaces que no se cierran al finalizar la ejecución de un script. Cuando se solicita una conexión persistente, PHP comprueba si ya hay una idéntica (que ya estuviera abierta antes), utilizándola si existe. Si no, crea el enlace. Una conexión «idéntica» es una conexión que fue abierta por el mismo host, con el mismo usuario y la misma contraseña (donde sea aplicable).
Aquellos que no están plenamente familiarizados con la forma en que trabajan y distribuyen la carga los servidores web podrían confundir para qué sirven las conexiones persistentes. En particular, con ellasnose pueden abrir «sesiones de usuario» en un mismo enlace,nose puede construir una transacción eficiente y no hacen muchísimas otras cosas. De hecho, para ser sumamente precisos, las conexiones persistentes no proporcionanningunaotra funcionalidad que no fuera posible realizar con sus hermanas no persistentes.
¿Por qué?
Esto tiene que ver con la manera en que los servidores web funcionan. Existen tres formas en las cuales un servidor web puede generar páginas web usando PHP.
El primer método es emplear PHP como una «envoltura» CGI. Cuando se ejecuta de esta forma, se crea y se destruye una instancia del intérprete de PHP por cada solicitud de página (para una página de PHP) al servidor web. Debido a que esta instancia se destruye después de cada solicitud, cualquier recurso que adquiera (tal como un enlace a un servidor de base de datos SQL) es cerrado en la destrucción de dicha instancia. En este caso, no se gana nada utilizando conexiones persistentes: simplemente no persisten.
El segundo método, y más popular, es ejecutar PHP como módulo en un servidor web multiproceso, lo que actualmente solo incluye a Apache. Un servidor multiproceso normalmente tiene un proceso (el padre) que coordina un grupo de procesos (sus hijos) los cuales son los que realmente hacen el trabajo de servir páginas web. Cuando una solicitud proviene de un cliente, esta es cedida a uno de los hijos que no esté ya sirviendo a otro cliente. Esto significa que cuando el mismo cliente hace una segunda solicitud al servidor, esta podría ser servida por un proceso hijo diferente a la primera vez. Cuando se abre una conexión persistente, cada página que solicite servicios SQL puede reusar la misma conexión establecida al servidor SQL.
El último método es utilizar PHP como complemento para un servidor web multihilo. Actualmente, PHP tiene soporte para ISAPI, WSAPI, y NSAPI (en Windows), las cuales permiten usar PHP como un complemento en servidores multihilo como Nestcape FastTrack (iPlanet), Microsoft Internet Information Server (IIS), y O'Reilly's WebSite Pro. El comportamiento es esencialmente el mismo para el modelo multiproceso descrito antes.
Si las conexiones persistentes no tienen ninguna funcionalidad adicional, ¿para que son útiles?
La respuesta es extremadamente simple: Eficacia. Las conexiones persistentes son buenas si la sobrecarga para crear enlaces al servidor SQL es alta. Que esta sobrecarga sea realmente alta o no depende de muchos factores, como el tipo de base de datos que se emplea, si esta se encuentra en la misma computadora en la que está el servidor web, la carga de la máquina donde está el servidor SQL, etc. En resumidas cuentas, si la sobrecarga de una conexión es alta, las conexiones persistentes ayudan considerablemente, haciendo que un proceso hijo únicamente se conecte una vez durante su vida útil, en lugar de hacerlo cada vez que procese una página que requiera una conexión al servidor SQL. Esto significa que cada hijo que abra una conexión persistente tendrá su propia conexión persistente abierta al servidor. Por ejemplo, si se tienen 20 procesos hijos diferentes que ejecutan un script que realiza una conexión persistente al servidor SQL, se tendrán 20 conexiones diferentes al servidor SQL, una por cada hijo.
Observe, sin embargo, que esto puede tener algunos inconvenientes si se está usando una base de datos con un limite de conexiones que sea excedido por las conexiones persistentes hijas. Si la base de datos tiene un limite de 16 conexiones simultáneas, y en el curso de una sesión de un servidor ocupado 17 hilos hijos intentan conectarse, uno de ellos no será capaz de hacerlo. Si un script contiene errores que impidan el cierre de las conexiones (como un bucle infinito), la mencionada base de datos con solamente 16 conexiones podría saturarse rápidamente. Compruebe la documentación de su base de datos para obtener información sobre el manejo conexiones abandonadas o inactivas.
Hay un par de advertencias más a tener en cuenta cuando se utilizan conexiones persistentes. Una es que cuando se usan bloqueos de tablas con una conexión persistente, si el script por alguna razón no puede liberar el bloqueo, los scripts subsiguientes que empleen la misma conexión quedarán en espera indefinidamente, puediendo ser necesario reiniciar el servidor httpd o el servidor de la base de datos. Otra cosa es que cuando se usan transacciones, un bloque de las mismas también acarrearía al siguiente script que utiliza la conexión si la ejecución del script termina antes de que el bloque lo haga. En cualquier caso, se puede usarregister_shutdown_function()para registrar una función de limpieza para desbloquear las tablas o deshacer las transacciones. Mejor aún, evitar este problema por completo no usando conexiones persistentes en scripts que utilicen bloqueos de tablas o transacciones (aún se pueden usar en otros lugares).
Un resumen importante. Las conexiones persistentes fueron diseñadas para tener una correspondencia uno a uno con las conexiones normales. Esto significa quesiemprese pueden reemplazar las conexiones persistentes por conexiones no persistentes, no cambiando así la forma de funcionar un script. Estopodría(y probablemente lo hará) cambiar la eficacia del script, aunque no su funcionamiento.
Véanse tambiénibase_pconnect(),ociplogon(),odbc_pconnect(),oci_pconnect(),pfsockopen()ypg_pconnect().
El principal objetivo de la SAPI CLI es el desarrollo de aplicaciones de consola con PHP. En este capítulo se explican las diferencias que hay entre la SAPI CLI y otrasSAPI. Vale la pena aclarar queCLIyCGIsonSAPIdiferentes pese a que comparten la mayoría de características.
La SAPI CLI se habilita por omisión con--enable-cli, aunque puede deshabilitarse usando la opción--disable-clial ejecutar./configure.
Tanto el nombre, ubicación y presencia de los binarios deCLI/CGIdiferirán dependiendo de cómo se instale PHP en el sistema. Al ejecutarmakede manera predeterminada,CGIyCLIse construyen y ubican comosapi/cgi/php-cgiysapi/cli/phprespectivamente, en el directorio origen de PHP. Debe tenerse en cuenta que las dos se llamanphp. Lo que suceda durante la ejecución demake installdependerá de la línea de configuración. Si durante la configuración se elige unaSAPIde módulo, tal como apxs, o bien se usa la opción--disable-cgi, se copiaráCLIa{PREFIJO}/bin/phpal ejecutarmake install; de lo contrario se colocaráCGIahí. Por ejemplo, si se utiliza--with-apxsen la línea de configuración,CLIse copiaría a{PREFIJO}/bin/phpdurantemake install. Si se desea sobrescribir la instalación del binario deCGI, debe usarsemake install-clitrasmake install. Alternativamente se puede especificar--disable-cgien la línea de configuración.
Nota:
Ya que tanto--enable-clicomo--enable-cgiestán habilitadas predeterminadamente, el simple hecho de tener--enable-clien la línea de configuración no implica queCLIse copie como{PREFIJO}/bin/phpdurantemake install.
Desde PHP 5, en Windows el binario deCLIse distribuye en la carpeta principal con el nombre dephp.exe. La versiónCGIse distribuye comophp-cgi.exe. Además, se distribuye un ficherophp-win.exesi PHP se configuró con--enable-cli-win32. Este funciona igual que la versiónCLI, solo que no muestra ninguna salida y, por tanto, no proporciona ninguna consola.
Nota:¿Qué SAPI tengo?
Desde la consola, al escribirphp -vsabremos siphpesCGIoCLI. Véase también la funciónphp_sapi_name()y la constante
PHP_SAPI.
Nota:
En Unix hay disponible una página del
manual escribiendoman phpen la terminal.
Principales diferencias de laSAPICLIrespecto a otrasSAPI:
A diferencia de laSAPICGI, no se envía ninguna cabecera a la salida.
Pese a que laSAPICGItiene un mecanismo para suprimir las cabeceras HTTP, no existe un equivalente para habilitarlas en la SAPI CLI.
Por omisión,CLIse inicia en modo silencioso, si bien se mantienen las opciones-qy--no-headerpor motivos de compatibilidad, de forma que pueda ser posible utilizar antiguos scriptsCGI.
No se cambia el directorio de trabajo al del script (las opciones-Cy--no-chdirse mantienen por compatibilidad).
Mensajes de error en texto plano (no se formatean enHTML).
Hay ciertas directivas dephp.inique se ignoran en la SAPI CLI debido a que no tienen sentido en un entorno de consola:
| Directiva | Valor predeterminado en laSAPICLI | Comentario |
|---|---|---|
| html_errors | false | Su valor predeterminado esfalse, ya que puede resultar complicado leer mensajes de error en la consola cuando estos están mezclados con etiquetasHTMLno interpretadas. |
| implicit_flush | true | En un entorno de consola, es preferible que las salidas que procedan deprint,echoy y similares se muestren inmediatamente y no se mantenga en memoria intermedia. Aun así, es posible utilizaroutput bufferingpara postergar o manipular la salida estándar. |
| max_execution_time | 0 (ilimitado) | PHP, en un entorno de consola, tiende a utilizarse para una gama mucho más amplia de los propósitos típicos de scripts basados en web, y como éstos pueden ser de muy larga duración, el tiempo de ejecución máximo se establece a ilimitado. |
| register_argc_argv | true | Establecer esta directiva a Las variables de PHP$argcy$argvse establecen automáticamente al valor apropiado cuando se utiliza laSAPICLI. Esos valores se pueden encontrar también en el array$_SERVER, por ejemplo:$_SERVER['argv'] |
| output_buffering | false | Aunque la directivaphp.iniestá codificada como |
| max_input_time | false | CLIde PHP no tiene soporte para GET, POST o subidas de ficheros. |
Nota:
Estas directivas no pueden ser inicializadas con otro valor desde el fichero de configuraciónphp.inio con un valor personalizado (si se especifica). Esta limitación se debe a que los valores son aplicados después que todos los ficheros de configuración han sido analizados. Sin embargo, sus valores pueden ser cambiados en tiempo de ejecución (aunque esto no es aplicable a todas ellas, comoregister_argc_argv).
Nota:
Se recomienda establecerignore_user_aborten scripts de línea de comandos. Para más información, consulteignore_user_abort().
Para facilitar el trabajo en entornos de consola, se definen varias constantes paraflujos de entrada/salida.
La SAPI CLInocambia el directorio actual a aquel en el que se encuentra el script ejecutado.
Ejemplo #1 Ejemplo que muestra las diferencias respecto a laSAPICGI:
<?php
// Aplicación de pruebas llamada test.php
echogetcwd(),"\n";
?>Al usar la versiónCGI, la salida es:
$ pwd /tmp $ php -q otro_directorio/test.php /tmp/otro_directorio
Esto muestra claramente que PHP cambia el directorio actual a aquel en que se encuentre el script ejecutado.
Al usar la SAPI CLI se obtiene:
$ pwd /tmp $ php -f otro_directorio/test.php /tmp
Esto ofrece una gran flexibilidad a la hora de escribir herramientas de consola en PHP.
Nota:
LaSAPICGIadmite este comportamiento propio de la SAPI CLI mediante la opción-Cal ejecutarlo desde la línea de comandos.
Se puede consultar en cualquier momento la lista de opciones de línea de comandos en el binario de PHP con el modificador-h:
Usage: php [opciones] [-f] <fichero> [--] [args...]
php [opciones] -r <código> [--] [args...]
php [opciones] [-B <código_inicial>] -R <código> [-E <código_final>] [--] [args...]
php [opciones] [-B <código_inicial>] -F <fichero> [-E <código_final>] [--] [args...]
php [opciones] -- [args...]
php [opciones] -a
-a Se ejecuta interactivamente.
-c <ruta>|<fichero> Busca el fichero php.ini en este directorio.
-n No se usará el fichero php.ini.
-d foo[=bar] Define la entrada INI de foo con el valor 'bar'
-e Generate información extendida para el depurador/perfilador.
-f <fichero> Analiza y ejecuta el <fichero>.
-h Esta ayuda.
-i Información de PHP.
-l Solamente revisa la sintáxis (lint).
-m Muestra lo compilado en módulos.
-r <code> Ejecuta el <código> PHP sin utilizar las etiquetas del script <?..?>.
-B <código_inicial> Ejecuta el <código_inicial> antes de procesar las líneas de entrada.
-R <code> Ejecuta el <código> PHP por cada línea de entrada.
-F <file> Analiza y ejecuta el <fichero> por cada línea de entrada.
-E <código_final> Ejecuta el <código_final> después de procesar todas las líneas de entrada.
-H Oculta los argumentos pasados desde cualquier herramienta externa.
-S <dirección>:<puerto> Ejecuta con el servidor web interno.
-t <raíz_documento> Especifica la raíz del documento <raíz_documento> para el servidor web interno.
-s Salida de la fuente en sintáxis HTML resaltada.
-v Número de versión.
-w Salida de la fuente con espacios en blanco y comentarios subrayados.
-z <fichero> Carga un <fichero> con extensión de Zend.
args... Argumentos pasados al script. Utilice argumentos con -- cuando el primer argumento
inicie con - o el script sea leído desde la entrada estándar stdin
--ini Muestra los nombres de fichero de configuración.
--rf <nombre> Muestra información sobre la función <nombre>.
--rc <nombre> Muestra información acerca de la clase <nombre>.
--re <nombre> Muestra información acerca de la extensión <nombre>.
--rz <nombre> Muestra información acerca de la extensión Zend <nombre>.
--ri <nombre> Muestra la configuración para la extensión <nombre>.
| Opción | Opción Larga | Descripción | |||
|---|---|---|---|---|---|
| -a | --interactive | Ejecutar PHP de forma interactiva. Para más información, consúltese la secciónConsola interactiva. | |||
| -b | --bindpath | Ruta Ligada en modo de servidor FASTCGI externo (sólo enCGI). | |||
| -C | --no-chdir | No cambiar el directorio del script (sólo enCGI). | |||
| -q | --no-header | Modo silencioso. Elimina la salida de cabecerasHTTP(sólo enCGI). | |||
| -T | --timing | Calcula el tiempo de ejecución del script unnúmerode veces (sólo enCGI). | |||
| -c | --php-ini | Especifica ya sea un directorio en el que se busca aphp.inio bien un fichero $ php -c /directorio/propio/mi_script.php $ php -c /directorio/propio/fichero-propio.ini mi_script.php Si no se especifica esta opción, se busca el ficherophp.inien laslocalizaciones predeterminadas. | |||
| -n | --no-php-ini | Ignorar por completo el ficherophp.ini. | |||
| -d | --define | Establecer un valor predeterminado para cualquiera de las directivas de configuración permitidas enphp.ini. Ésta es la sintaxis: -d directiva_de_configuracion[=valor]
# Si se omite el valor, se establecerá un "1" a la directiva
$ php -d max_execution_time
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"
# Si se pasa un valor vacío, se establecerá "" a la directiva
php -d max_execution_time=
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""
# Se pasará lo que haya tras el caracter '=' a la directiva de configuración
$ php -d max_execution_time=20
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$ php
-d max_execution_time=doesntmakesense
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"
| |||
| -e | --profile-info | Activa el modo de información expandida, para usar con un depurador/perfilador. | |||
| -f | --file | Analiza y ejecuta el fichero proporcionado. El modificador-fes opcional y puede ser omitido - es suficiente con solo poner el nombre del fichero a ejecutar.
| |||
| -h y -? | --help y --usage | Muestra una lista de opciones de línea de comandos, con descripciones de una línea sobre lo que hace. | |||
| -i | --info | Invoca aphpinfo(), y muestra el resultado. Si PHP no funcionara correctamente, es aconsejable utilizarphp -ipara ver donde se muestre cualquier mensaje de error antes o en el lugar de las tablas de información. Tenga en cuenta que al usarse en modoCGIla salida es enHTMLy por lo tanto muy larga. | |||
| -l | --syntax-check | Provee un método conveniente para realizar solamente una revisión de sintáxis del código proporcionado de PHP. En caso de éxito, se muestra el texto Esta opción no encuentra errores fatales (como funciones no definidas). Utilice el modificador-fsi se desea también comprobar errores fatales.
| |||
| -m | --modules | Ejemplo #1 Muestra los módulos PHP y Zend incorporados (y habilitados) $ php -m [PHP Modules] xml tokenizer standard session posix pcre overload mysql mbstring ctype [Zend Modules] | |||
| -r | --run | Permite ejecutar PHP desde la línea de comandos. Las etiquetas de inicio y fin (
| |||
| -B | --process-begin | Código PHP a ejecutar antes de procesar la entrada. Añadido en PHP 5. | |||
| -R | --process-code | Código PHP a ejecutar por cada línea de entrada. Añadido en PHP 5. Hay dos variables especiales disponibles en este modo:$argny$argi.$argncontendrá la línea que PHP está procesando en un momento dado, mientras que$argicontendrá el número de línea. | |||
| -F | --process-file | Fichero PHP a ejecutar por cada línea de entrada. Añadido en PHP 5. | |||
| -E | --process-end | Código PHP a ejecutar tras procesar cada línea. Añadido en PHP 5. Ejemplo #4 Usando las opciones-B,-Ry-Epara contar el número de líneas de un proyecto. $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";' Total Lines: 37328 | |||
| -S | --server | Inicia elservidor web interno. Disponible a partir de PHP 5.4.0. | |||
| -t | --docroot | Especifiva la raíz del documento para elservidor web interno. Disponible a partir de PHP 5.4.0. | |||
| -s | --syntax-highlight y --syntax-highlighting | Mostrar el código fuente destacando la sintaxis en color. Esta opción utiliza los mecanismos internos de análisis del ficheros y escribe una versión HTML coloreada y la muestra en la salida estándar. Tenga en cuenta que todo lo que hace es generar un bloque de etiquetas HTML
| |||
| -v | --version | Ejemplo #5 Al usar-vobtenemos el nombre de laSAPIy la versión de PHP y Zend $ php -v PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07) Copyright (c) 1997-2009 The PHP Group Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies | |||
| -w | --strip | Mostrar código fuente sin comentarios ni líneas en blanco.
| |||
| -z | --zend-extension | Carga una extensión Zend. Si sólo se proporciona un nombre de fichero, PHP trata de cargar la extensión en el directorio de bibliotecas por defecto de su sistema (normalmente se especifica en/etc/ld.so.confen sistemas Linux, por ejemplo). Si se proporciona un nombre de fichero con la ruta absoluta no se usarán las rutas de bibliotecas del sistema. Un nombre de fichero relativo que incluya algún directorio le indicará a PHP que sólo trate de cargar la extensión a partir del directorio actual. | |||
| --ini | Mostrar el nombre del fichero de configuración y de los directorios analizados. Disponible desde PHP 5.2.3. Ejemplo #6 Ejemplo de $ php --ini Configuration File (php.ini) Path: /usr/dev/php/5.2/lib Loaded Configuration File: /usr/dev/php/5.2/lib/php.ini Scan for additional .ini files in: (none) Additional .ini files parsed: (none) | ||||
| --rf | --rfunction | Mostrar información de la función o método proporcionado (p.ej. número y nombre de los parámetros). Disponible desde PHP 5.1.2. Esta opción sólo está disponible si se compiló PHP con soporte paraReflection. Ejemplo #7 Uso básico de $ php --rf var_dump
Function [ <internal> public function var_dump ] {
- Parameters [2] {
Parameter #0 [ <requerido> $var ]
Parameter #1 [ <opcional> $... ]
}
} | |||
| --rc | --rclass | Muestra información de la clase dada (lista de constantes, propiedades y métodos). Disponible desde PHP 5.1.2. Esta opción sólo está disponible si se compiló PHP con soporte paraReflection. Ejemplo #8 Ejemplo de $ php --rc Directory
Class [ <internal:standard> class Directory ] {
- Constants [0] {
}
- Static properties [0] {
}
- Static methods [0] {
}
- Properties [0] {
}
- Methods [3] {
Method [ <internal> public method close ] {
}
Method [ <internal> public method rewind ] {
}
Method [ <internal> public method read ] {
}
}
} | |||
| --re | --rextension | Muestra información de la extensión dada (lista de opciones enphp.ini, funciones definidas, constantes y clases). Disponible desde PHP 5.1.2. Esta opción sólo está disponible si se compiló PHP con soporte paraReflection. Ejemplo #9 Ejemplo de $ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {
- Functions {
Function [ <internal> function json_encode ] {
}
Function [ <internal> function json_decode ] {
}
}
} | |||
| --rz | --rzendextension | Mostrar la información de configuración para la extensión Zend proporcionada (la misma información que es devuelta por la funciónphpinfo()). Disponible como parte de PHP 5.4.0. | |||
| --ri | --rextinfo | Mostrar información de configuración de la extensión dada (la misma información que muestraphpinfo()). Disponible desde PHP 5.2.2. La información relevante está disponible usando "main" como nombre de extensión. Ejemplo #10 Ejemplo de $ php --ri date date date/time support => enabled "Olson" Timezone Database Version => 2009.20 Timezone Database => internal Default timezone => Europe/Oslo Directive => Local Value => Master Value date.timezone => Europe/Oslo => Europe/Oslo date.default_latitude => 59.930972 => 59.930972 date.default_longitude => 10.776699 => 10.776699 date.sunset_zenith => 90.583333 => 90.583333 date.sunrise_zenith => 90.583333 => 90.583333 |
| Constante | Descripción | ||||
|---|---|---|---|---|---|
STDIN | Flujo abierto a <?phpstdin, puede usarse<?php | ||||
STDOUT | Flujo abierto a <?php | ||||
STDERR | Flujo abierto a <?php |
| Sequence: | Description: |
|---|---|
\e | Utilizado para agregar colores al ingreso de órdenes. Un ejemplo podría ser\e[032m\v \e[031m\b \e[34m\> \e[0m |
\v | La versión de PHP. |
\b | Indica cual bloque de PHP está dentro. Por ejemplo/*se usa para indicar que está dentro de un comentario multilineal. El alcance externo es denotado porphp. |
\> | Indica el caracter de ingreso de órdenes. El caracter predeterminado es>, pero cambia cuando la shell está dentro de un bloque indeterminado o una cadena. Los caracteres posibles son:' " { ( > |
Nota:
Los ficheros que se han incluido en este modo medianteauto_prepend_fileyauto_append_filese analizan con algunas restricciones - p.ej. las funciones deben estar definidas antes de que se carguen.
Nota:
Laauto-cargano está disponible al usar PHP en modo interactivo enCLI.
Este servidor web ha sido diseñado para ayudar al desarrollo de aplicaciones. También puede ser útil para propósitos de prueba o para demostraciones de aplicaciones que se ejecutan en entornos controlados. No se pretende que sea un servidor web con todas las funciones. No debe ser utilizado en una red pública.
Desde PHP 5.4.0, la SAPI CLI provee un servidor web embebido.
El servidor web ejecuta solamente un único proceso monohilo, por lo que las aplicaciones PHP se detendrán si la solicitud está bloqueada.
Las peticiones de URI se sirven desde el actual directorio de trabajo donde PHP se inició, a menos que la opción -t sea utilizada para especificar una raíz de documentos explícita. Si una petición de URI no especifica un fichero, entonces el index.php o index.html que estén en el directorio dado serán devueltos. Si ninguno de los ficheros existen, la búsqueda de index.php e index.html continuará en el directorio padre y continuará así hasta encontrar uno de ello o se alcance el directorio raíz. Si se encuentra index.php o index.html, se devuelve este y $_SERVER['PATH_INFO'] se establece a la parte final del URI. De lo contrario se devuelve un código de respuesta 404.
Si un fichero PHP es proporcionado en la línea de comandos cuando se inicia el servidor web éste es tratado como un script "enrutador". El script es ejecutado al inicio de cada petición HTTP. Si este script devuelvefalse, entonces el recurso solicitado se devuelve tal cual está. De otra forma la salida del script se devuelve en el navegador.
Los tipos MIME estándar son devueltos para ficheros con extensiones: .3gp, .apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz, .gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz, .m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg, .ogv, .pdf, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text, .tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, y .zip.
| Versión | Descripción |
|---|---|
| 5.5.12 | .xml, .xsl, and .xsd |
| 5.5.7 | .3gp, .apk, .avi, .bmp, .csv, .doc, .docx, .flac, .gz, .gzip, .ics, .kml, .kmz, .m4a, .mp3, .mp4, .mpg, .mpeg, .mov, .odp, .ods, .odt, .oga, .pdf, .pptx, .pps, .qt, .swf, .tar, .text, .tif, .wav, .wmv, .xls, .xlsx, y .zip |
| 5.5.5 | |
| 5.4.11 | .ogg, .ogv, and .webm |
| 5.4.4 | .htm and .svg |
Ejemplo #1 Iniciando el servidor web
$ cd ~/public_html $ php -S localhost:8000
La terminal mostrará:
PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:43:28 2011 Escuchando en localhost:8000 La raíz de documentos es /home/usuario/html_público Presione Ctrl-C para salir
Después de una petición de una URI para http://localhost:8000/ y http://localhost:8000/mi_script.html la terminal mostrará algo similar a:
PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:43:28 2011 Escuchando en localhost:8000 La raíz de documentos es /home/usuario/html_público Presione Ctrl-C para salir. [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Petición leída [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Petición leída [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Petición leída [Thu Jul 21 10:48:52 2011] ::1:39148 GET /mi_script.html - Petición leída [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Petición leída
Ejemplo #2 Iniciando con una raíz de documentos específica
$ cd ~/html_público $ php -S localhost:8000 -t foo/
La terminal mostrará:
PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:50:26 2011 Escuchando en localhost:8000 La raíz de documentos es /home/usuario/html_público/foo Presione Ctrl-C para salir
Ejemplo #3 Utilizando un Script enrutador
En este ejemplo, las peticiones a las imágenes se mostrarán, pero las peticiones a ficheros HTML mostrarán "Bienvenido a PHP":
<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/',$_SERVER["REQUEST_URI"])){
returnfalse;// servir la petición tal cual es.
}else {
echo"<p>Bienvenido a PHP</p>";
}
?>$ php -S localhost:8000 router.php
Ejemplo #4 Revisión del uso de la CLI del servidor web
Para reutilizar un framework de script enrutador durante el desarrollo con la CLI del servidor web server y luego con un servidor web en producción:
<?php
// router.php
if (php_sapi_name() =='cli-server') {
/* los activos de ruta estática y devolver falso */
}
/* seguir adelante con operaciones normales de index.php */
?>$ php -S localhost:8000 router.php
Ejemplo #5 Manejando tipos de ficheros no soportados
Si necesita servir un recurso estático cuyo tipo MIME no es manejado por la CLI del servidor web, utilice:
<?php
// router.php
$path=pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] =="el") {
header("Content-Type: text/x-script.elisp");
readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
returnFALSE;
}
?>$ php -S localhost:8000 router.php
Ejemplo #6 Accediendo a la CLI del servidor web desde máquinas remotas
Puede hacer que el servidor web sea accesible en el puerto 8000 a cualquier interfaz con:
$ php -S 0.0.0.0:8000
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| cli_server.color | "0" | PHP_INI_ALL | Disponible desde PHP 5.4.0. |
He aquí una breve explicación de las directivas de configuración.
cli_server.colorbooleanHabilita el servidor web de desarrollo interno para usa la codificación de color ANSI en la salida del terminal.
Esta sección explica las ventajas del nuevo mecanismo de Recoleción de basura (GC por sus siglas en inglés de «Garbage Collection») de la versión 5.3 de PHP.
Una variable en PHP se almacena en un contenedor llamado "zval". Un contenedor zval contiene, además del tipo de la variable y su valor, dos bits adicionales de información. Al primero se le llama "is_ref" y contiene un valor booleano que indica si la variable es parte o no de un "conjunto de referencias". Con este bit, el motor de PHP sabe diferenciar entre variables normales y referencias. Puesto que PHP permite referencias definidas por el usuario, tal y como se crean con el operador &, un contenedor zval tiene también un mecanismo contador de referencias para optimizar el uso de memoria. Esta segunda pieza adicional de información, llamada "refcount", contiene el número de variables (también llamadas símbolos) que apuntan a este contenedor zval. Todos los símbolos se almacenan en una tabla de símbolos, de las cuales hay una por cada ámbito. Hay un ámbito para el script principal (es decir, el solicitado por el navegador), además de uno por cada función o método.
Se crea un contenedor zval al crear una nueva variable con un valor constante, como por ejemplo:
Ejemplo #1 Creación de un nuevo contenedor zval
<?php
$a="nuevo string";
?>En este caso, el nombre del nuevo símbolo,a, se crea en el ámbito actual y se crea un nuevo contenedor de variable con el tipostringy el valornuevo string. El bit "is_ref" se establece por omisión afalsedado que no se ha creado ninguna referencia en el espacio del usuario. "refcount" se establece a1, pues solo hay un símbolo que haga uso de este contenedor de variable. Tenga en cuenta que si "refcount" es1, "is_ref" siempre valdráfalse. Si tiene» Xdebuginstalado, puede mostrar esta información llamando axdebug_debug_zval().
Ejemplo #2 Mostrar información de zval
<?php
$a="nuevo string";
xdebug_debug_zval('a');
?>El resultado del ejemplo sería:
a: (refcount=1, is_ref=0)='nuevo string'
Al asignar esta variable a otro nombre de variable, se incrementará refcount.
Ejemplo #3 Incremento de refcount de un zval
<?php
$a="nuevo string";
$b=$a;
xdebug_debug_zval('a');
?>El resultado del ejemplo sería:
a: (refcount=2, is_ref=0)='nuevo string'
Aquí, refcount vale2, pues el mismo contenedor de variable está vinculado tanto poracomo porb. PHP es lo suficiente inteligente para no copiar el contenedor de variable en sí cuando no es necesario. Los contenedores de variables se destruyen cuando "refcount" llega a cero. "refcount" se decrementa en uno cuando alguno de los símbolos vinculados al contenedor de variable abandona su ámbito (p.ej. cuando finaliza una función) o cuando un símbolo es desasignado (p. ej., llamando aunset()). El siguiente ejemplo muestra esto:
Ejemplo #4 Decremento de refcount de zval
<?php
$a="nuevo string";
$c=$b=$a;
xdebug_debug_zval('a');
$b=42;
xdebug_debug_zval('a');
unset($c);
xdebug_debug_zval('a');
?>El resultado del ejemplo sería:
a: (refcount=3, is_ref=0)='nuevo string' a: (refcount=2, is_ref=0)='nuevo string' a: (refcount=1, is_ref=0)='nuevo string'
Si ahora llamáramos aunset($a);, el contenedor de variable, incluyendo tanto el tipo como el valor, se eliminarían de la memoría.
Las cosas se complican con tipos compuestos tales comoarrays yobject. En lugar de un valor de tiposcalar, losarrays yobjects almacenan sus propiedades en su propia tabla de símbolos. Esto significa que el siguiente ejemplo crea tres contenedores zval:
Ejemplo #5 Crear un zval de tipoarray
<?php
$a= array('meaning'=>'life','number'=>42);
xdebug_debug_zval('a');
?>El resultado del ejemplo sería algo similar a:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=1, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42 )
Gráficamente

Los tres contenedores zval son:a,meaning, ynumber. Se aplican reglas similares a la hora de incrementar y decrementar "refcounts". Abajo, añadimos otro elemento al array, y fijamos su valor al contenido de un elemento ya existente:
Ejemplo #6 Añadir un elemento existente a un array
<?php
$a= array('meaning'=>'life','number'=>42);
$a['life'] =$a['meaning'];
xdebug_debug_zval('a');
?>El resultado del ejemplo sería algo similar a:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=2, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42, 'life' => (refcount=2, is_ref=0)='life' )
Gráficamente

A partir de la salida de Xdebug, vemos que tanto el antiguo como el nuevo elemento del array apuntan a un contenedor zval cuyo "refcount" vale2. Pese a que Xdebug muestra dos contenedores zval con valor'life', son el mismo. La funciónxdebug_debug_zval()no muestra esto, aunque podria comprobarse mostrando también el puntero de memoria.
Eliminar un elemento del array es como eliminar un símbolo de un ámbito. Al hacerlo, el "refcount" del contenedor al que apunta el elemento del array se decrementa. De nuevo, cuando "refcount" alcanza cero, el contenedor de la variable se elimina de la memoria. Un ejemplo que muestra esto:
Ejemplo #7 Eliminar un elemento de un array
<?php
$a= array('meaning'=>'life','number'=>42);
$a['life'] =$a['meaning'];
unset($a['meaning'],$a['number'] );
xdebug_debug_zval('a');
?>El resultado del ejemplo sería algo similar a:
a: (refcount=1, is_ref=0)=array ( 'life' => (refcount=1, is_ref=0)='life' )
Ahora, las cosas se vuelven interesantes si añadimos al propio array como elemento del array, como veremos en el siguiente ejemplo, en el que también usaremos el operador de referencia, ya que de lo contrario PHP crearía una copia:
Ejemplo #8 Añadir el propio array como elemento de sí mismo
<?php
$a= array('one');
$a[] =&$a;
xdebug_debug_zval('a');
?>El resultado del ejemplo sería algo similar a:
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=2, is_ref=1)=... )
Gráficamente

Puede verse que tanto la variable de tipo array (a) como el segundo elemento (1) apuntan ahora a un contenedor de variable que tiene un "refcount" de2. Los "..." mostrados arriba indican que hay una referencia cíclica, lo cual, por supuesto, significa que en este caso los "..." apuntan al array original.
Al igual que antes, al eliminar una variable se elimina el símbolo y el contador de referencias del contenedor de variable al que apunte se decrementa en uno. De modo que, si eliminamos la variable$adespués de ejecutar el código anterior, el contador de referencias del contenedor de variable al que apuntan tanto$acomo el elemento "1" se decrementa en uno, de "2" a "1". Se puede representar así:
Ejemplo #9 Eliminar$a
(refcount=1, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=1, is_ref=1)=... )
Gráficamente

Pese a que ya no hay ningún símbolo en ningún ámbito que apunte a esta estructura, esta no se puede limpiar ya que el elemento "1" del array todavía apunta al mismo array. Al no haber un símbolo externo que apunte a él, no hay forma por la que el usuario pueda eliminar esta estructura; por tanto tenemos una fuga de memoria. Afortunadamente, PHP limpiará esta estructura de datos al finalizar la petición, aunque hasta entonces esté ocupando un valioso espacio de memoria. Esta situación ocurre a menudo si se está implementando un algoritmo de análisis o en otras situaciones en las que un nodo hijo apunte de nuevo a un elemento "padre". Por supuesto, esta situación también puede suceder con objetos, donde es más frecuente que ocurra, ya que los objetos siempre se usan implícitamente por referencia.
Esto no debería ser un problema si sólo ocurre una o dos veces, pero si estas fugas de memoria suceden miles, o incluso millones de veces, lógicamente esto comenzaría a ser un problema. Es especialmente problemático en scripts de larga duración, tales como demonios donde básicamente nunca terminan las peticiones, o en un gran conjunto de pruebas unitarias. Esto último causó problemas al ejecutar las pruebas unitarias del componente Template de la biblioteca eZ Componentes. En algunos casos, podrían ser necesarios 2 GB de memoria que quizás no los tenga el servidor de pruebas.
Tradicionalmente, los mecanismos que contabilizan las referencias en memoria, tal como el que empleaba PHP anteriormente, fallaban al abordar las fugas de memoria de referencias cíclicas. Sin embargo, desde PHP 5.3.0 se implementa el algoritmo síncrono del artículo» Recolección de ciclos concurrentes en sistemas de contabilidad de referenciasque resuelve este asunto.
Una explicación detallada del funcionamiento del algoritmo queda más allá del objetivo de esta sección, aunque aquí explicaremos el mecanismo básico. Antes de nada, debemos establecer unas reglas básicas. Si se incrementa un refcount, este aún sigue en uso: no es basura. Si se decrementa el refcount y llega a cero, el zval puede liberarse. Esto significa que la recolección de ciclos sólo puede llevarse a cabo cuando un argumento refcount se decrementa a un valor que no sea cero. En segundo lugar, en un ciclo de recolección de basura, es posible averiguar qué partes son basura comprobando si se puede decrementar en uno sus refcount, para después comprobar cuáles zval poseen un refcount de cero.

Para evitar llamar a la comprobación de ciclos de basura en cada posible decremento de un refcount, el algoritmo lo que hace es pasar todas las posibles raíces (zvals) al "buffer raíz" (marcándolos en "púrpura"). También se asegura de que cada raíz de basura sólo finaliza una vez en el buffer. Únicamente cuando el buffer raíz está completo, comienza el mecanismo de recolección para todos los zval diferentes que haya en su interior. Véase el paso A en la figura anterior.
En el paso B, el algoritmo inicia una primera búsqueda en profundidad de todas las posibles raíces en las que decrementa por uno los refcount de los zval que encuentra, asegurándose de que no decrementa dos veces el mismo zval (marcándolo en "gris"). En el paso C, el algoritmo vuelve a llevar a cabo una búsqueda en profundidad dentro de cada nodo raíz, para volver a comprobar el refcount de cada zval. Si ve que el refcount es cero, se marca al zval en "blanco" (azul en la figura). Si es mayor que cero, deshace el decremento con una búsqueda en profundidad partiendo de ese punto, y se le vuelve a marcar en "negro". En el último paso (D), el algoritmo recorre el buffer raíz eliminando las raíces zval que haya, y a la vez, comprueba qué zvals se han marcado en "blanco" en el paso anterior. Todos los zval marcados en "blanco" se eliminarán.
Ahora que ya tiene un conocimiento básico de cómo funciona el algoritmo, volveremos atrás para ver cómo se integra esto en PHP. Por omisión, el recolector de basuras de PHP está habilitado. Hay, sin embargo, una directiva enphp.inique permite cambiar esto:zend.enable_gc.
Cuando el recolector de basura está habilitado, el algoritmo que busca ciclos, tal y como se ha descrito arriba, se ejecuta cada vez que se llena el buffer raíz. Éste tiene un tamaño fijo de 10.000 raíces posibles (se puede modificar esto cambiando la contanteGC_ROOT_BUFFER_MAX_ENTRIESenZend/zend_gc.cdel código fuente de PHP, y recompilando PHP). Cuando el recolector de basuras se deshabilita, no se ejecutará el algoritmo que busca ciclos. Sea como fuere, las posibles raíces seguirían registrándose en el buffer raíz, sin importar si el mecanismo recolector de basuras está habilitado en la configuración o no.
Si estando deshabilitado el mecanismo recolector de basuras se llenara el buffer raíz de posibles raíces, no se registraría al resto de raíces posibles, por lo que no llegarían a ser analizadas por el algoritmo. Si fueran parte de un ciclo de referencia circular, nunca se liberarían y podrían provocar una fuga de memoria.
La razón por la que se registran las posibles raíces estando deshabilitado el mecanismo es porque es más rápido registrarlas que comprobar en cada una de ellas si el mecanismo está habilitado. Sin embargo, el recolector de basuras y el propio mecanismo de análisis, sí puede conllevar una cantidad de tiempo considerable.
Ademas de poder cambiar la configuraciónzend.enable_gc, también es posible habilitar o deshabilitar el mecanismo recolector de basura llamando agc_enable()ogc_disable()respectivamente. La llamada a estas funciones tiene el mismo efecto que habilitar o deshabilitar el mecanismo en la propia configuración. También es posible forzar la recolección de ciclos incluso sin que esté lleno el buffer raíz. Para hacer esto, se puede usar la funcióngc_collect_cycles(). Esta función devuelve el número de ciclos que fueron recolectados por el algoritmo.
El motivo por el que es posible habilitar o deshabilitar el mecanismo, o iniciar los ciclos de recolección a mano, es porque podría haber determinadas partes de una aplicación que necesiten mucha precisión de tiempo. En estos casos, quizás no se desee que funcione el mecanismo recolector de basuras. Por supuesto, al deshabilitar el recolector de basuras en algunas partes del código, se corre el riesgo de provocar fugas de memoria, ya que algunas raíces podrían no caber en el buffer raíz. Por tanto, lo mas prudente sería llamar agc_collect_cycles()justo después de llamar agc_disable()para que libere la memoria ocupada por posibles raíces ya registradas en el buffer raíz. Esto deja por tanto un buffer vacío, de modo que queda más espacio para almacenar posibles raíces en el tiempo en que el mecanismo recolector de ciclos está deshabilitado.
Como mencionamos en la sección anterior, la recolección de raíces tiene muy bajo impacto en el rendimiento, pero aquí es cuando comparamos PHP 5.2 contra PHP 5.3. Si bien la recolección de posibles raíces comparado con la no recolección, como en PHP 5.2, es más lenta, hay otras modificaciones en tiempo de ejecución en PHP 5.3 que impiden que esta pérdida de rendimiento en particular pueda siquiera apreciarse.
Hay dos principales sectores en los que el rendimiento se ve afectado. El primero es el uso reducido de memoria, y mientras que el segunda es la reducción en tiempo de ejecución cuando el mecanismo recolector de basura lleva a cabo la limpieza de memoria. Revisaremos estos dos asuntos.
Antes de nada, la razón por la que se implementa el mecanismo recolector de basuras es para reducir el uso de memoria limpiando, una vez que se cumplen las condiciones, las variables de referencias circulares. En la implementación de PHP, esto sucede cuando el buffer raíz está lleno, o cuando se invoca la funcióngc_collect_cycles(). En el gráfico mostrado abajo, se muestra el uso de memoria tanto en PHP 5.2 como en 5.3, excluyendo la memoria base que el propio PHP ocupa al arrancar.
Ejemplo #1 Ejemplo de uso de memoria
<?php
classFoo
{
public$var='3.14159265359';
}
$baseMemory=memory_get_usage();
for ($i=0;$i<=100000;$i++ )
{
$a= newFoo;
$a->self=$a;
if ($i%500===0)
{
echosprintf('%8d: ',$i),memory_get_usage() -$baseMemory,"\n";
}
}
?>
En este ejemplo didáctico, estamos creando un objeto en el que una propiedad enlaza de nuevo al propio objeto. Cuando la variable$adel script se reasigna en la siguiente iteración del bucle, típicamente ocurriría una fuga de memoria. En este caso, se fugan dos contenedores zval (el zval del objeto, y el zval de la propiead), pero sólo se encuentra una posible raíz: la variable que se desasignó. Tras 10.000 iteraciones, el buffer se llena (con un total de 10.000 posibles raíces), y se lanza el mecanismo recolector de basura y libera la memoria asociada con esas posibles raíces. Puede apreciarse claramente en el uso de memoria "dentado" de la gráfica para PHP 5.3. Tras las 10.000 iteraciones, el mecanismo libera la memoria asociada a las variables con referencias cíclicas. En este ejemplo, el propio mecanismo no debe hacer un gran trabajo, puesto que la estructura que produce la fuga es extremadamente sencilla. A partir del diagrama, se puede comprobar que el uso máximo de memoria en PHP 5.3 es en torno a 9 Mb, mientras que en PHP 5.2 el uso de memoria no para de aumentar.
El segundo sector en el que el mecanismo recolector de basura influye en el rendimiento es en el tiempo que lleva a éste liberar la memoria "fugada". Para comprobar de cuánto estamos hablando, modificaremos ligeramente el script anterior para tener en cuenta un mayor número de iteraciones, y eliminaremos las figuras de uso de memoria intermedio. Este es el segundo script:
Ejemplo #2 Influencia en rendimiento de Recolector de Basuras
<?php
classFoo
{
public$var='3.14159265359';
}
for ($i=0;$i<=1000000;$i++ )
{
$a= newFoo;
$a->self=$a;
}
echomemory_get_peak_usage(),"\n";
?>Ejecutaremos dos veces este script, una con el ajustezend.enable_gchabilitado, y en la otra deshabilitado:
Ejemplo #3 Ejecutando el script anterior
time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php # and time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php
En la máquina de ejemplo, el primer comando parece llevar en torno a 10,7 segundos, mientras que al segundo comando le lleva 11,4. Esto es un incremento de en torno al 7%. Sin embargo, el uso máximo de memoria del script se ha reducido en un 98%, pasando de 931Mb a 10Mb. Esta prueba no es muy científica, ni siquiera representativa de aplicaciones reales, pero demuestra que el uso de memoria se beneficia del mecanismo recolector de basuras. Lo interesante es que para este script en particular el incremento es siempre del 7%, mientras que el ahorro de memoria aumenta a medida que se encuentran más referencias cíclicas en la ejecución del script.
Todavía es posible dar más información sobre cómo funciona el mecanismo recolector de basuras dentro de PHP. Pero para hacerlo, será necesario recompilar PHP para habilitar el código de análises y de recopilación de datos. Se tendrá que asignar a la variable de entornoCFLAGSel valor-DGC_BENCH=1antes de ejecutar./configurecon las opciones deseadas. La siguiente secuencia muestra cómo hacerlo:
Ejemplo #4 Recompilando PHP para habilitar el análisis del Recolector de Basuras
export CFLAGS=-DGC_BENCH=1 ./config.nice make clean make
Al ejecutar el ejemplo que vimos arriba con el nuevo binario de PHP que hemos creado, veremos que se muestra el siguiente resultado tras la ejecución de PHP:
Ejemplo #5 Estadísticas de Recolección de Basuras
GC Statistics
-------------
Runs: 110
Collected: 2072204
Root buffer length: 0
Root buffer peak: 10000
Possible Remove from Marked
Root Buffered buffer grey
-------- -------- ----------- ------
ZVAL 7175487 1491291 1241690 3611871
ZOBJ 28506264 1527980 677581 1025731Las estadísticas más informativas son las que se muestran en el primer bloque. Puede comprobarse que el mecanismo recolector de basuras se ejecutó 110 veces, y en total, se liberaron más de 2 millones de ubicaciones en memoria durante esas 110 ejecuciones. Puesto que el mecanismo recolector de ciclos se ha ejecutado al menos una vez, el "pico del buffer raíz" es siempre 10.000.
En general el recolector de basuras de PHP sólo provocará un retraso cuando el algoritmo recolector de ciclos funcione, mientras que en scripts normales (más pequeños) no habrá un impacto real en el rendimiento.
Sin embargo, en el caso en el que el mecanismo recolector de ciclos se ejecute para scripts normales, la reducción de memoria permitirá que puedan funcionar más scripts concurrentemente en el servidor, ya que en total no utilizarán mucha memoria.
Los beneficios son más evidentss en scripts de larga duración, tales como grandes suits de pruebas o scripts demonios. También en las aplicaciones» PHP-GTK, que generalmente suelen ejecutarse durante más tiempo que scripts para la Web; el nuevo mecanismo marcará la diferencia en cuanto a las fugas de memoria progresivas en el tiempo.
DTrace es un marco de rastreo de disponibilidad permanente, bajo consumo, y disponible en un gran número de plataformas incluyendo Solaris, Mac OS X, Oracle Linux y BSD. DTrace puede seguir el rastro del comportamiento del sistema operativo y la ejecución del programa del usuario. DTrace puede enseñar los valores de los argumentos y ser utilizados para inferir estadísticas de rendimiento. Los sondeos son monitorizados por scripts creados por el usuario, escritos en el programa de scripting DTrace D. Esto permite el análisis eficiente de puntos de datos.
Los sondeos en PHP que no son activamente monitorizados por scripts DTrace D del usuario no contienen código observado por lo cual no hay una degradación del rendimiento durante la ejecución normal de la aplicación. Los sondeos que estan siendo monitorizados incurren una perdida suficientemente baja para permitir monitorización con DTrace en entornos de producción activos.
PHP incorpora sondeos "User-level Statically Defined Tracing" (USDT) que son evaluados en tiempo de ejecución. Por ejemplo, cuando un script D está monitorizando unaentrada de función, cada ve que la función de PHP es llamada, dispararía el sondeo y el código de acción que ésta tiene asociado. Esta código de acción podría, por ejemplo, imprimir los argumentos del sondeo tales como lo ubicación del fichero con la función PHP, o podría contabilizar el número de veces que esta función fue llamada.
Sólo sondas PHP USDT son descritas aquí. Refierase a documentación externa sobre DTrace de sistema operativo para ver como puede DTrace ser usado para rastrear funciones arbitrarias, y como puede ser usado para rastrear el comportamiento del sistema operativo. Tenga en cuenta que no todas las funcionalidades de DTrace estan disponibles en todas las implementaciones de DTrace.
Las sondas estáticas de DTrace están incluidas en PHP 5.4. Previo a esto estaba incluidas via una extensión» PECL, que ahora ha quedado obsoleta.
Las sondas estáticas DTrace en PHP pueden alternativamente ser usadas con las herramientas de SystemTap en algunas distribuciones Linux.
PHP puede ser configurado con sondas estáticas DTrace en plataformas que soportan Rastreo Dinámico DTrace.
Refierase a la documentación externa específica par su plataforma para habilitar el soporte para rastreo DTrace en el sistema operativo. Por ejemplo, en Oracle Linux arranque con un kernel UEK3 y haga:
# modprobe fasttrap
# chmod 666 /dev/dtrace/helperEn lugar de utilizarchmod, usted podria utilizar una regla de paquete ACL para limitar acceso a los dispositivos a ciertos usuarios.
Compile PHP con el parámetro de configuración--enable-dtrace:
# ./configure --enable-dtrace ...
# make
# make installEsto habilita las sondas estáticas en el núcleo de PHP. Cualquiera de las extensiones que ofrezcan sus propios sondeos deberán ser compiladas de forma separada como extensiones compartidas.
| Nombre del Sondeo | Descripción del Sondeo | Argumentos del Sondeo |
|---|---|---|
request-startup | Se dispara cuando comienza una petición. | char *file, char *request_uri, char *request_method |
request-shutdown | Se dispara cuando se termina una petición. | char *file, char *request_uri, char *request_method |
compile-file-entry | Se dispara cuando la compilación de un script comienza. | char *compile_file, char *compile_file_translated |
compile-file-return | Se dispara cuando la compilación de un script termina. | char *compile_file, char *compile_file_translated |
execute-entry | Se dispara cuando un código de operación array está por ser ejecutado. Por ejemplo, se dispara en llamadas a funciones, includes, y continuaciones de resumes. | char *request_file, intlineno |
execute-return | Se dispara después de la ejecución de un código de operación array. | char *request_file, intlineno |
function-entry | Se dispara cuando el motor de PHP entra a la llamada de una función o método. | char *function_name, char *request_file, intlineno, char *classname, char *scope |
function-return | Se dispara cuando el motor de PHP regresa de la llamada a una función o método. | char *function_name, char *request_file, intlineno, char *classname, char *scope |
exception-thrown | Se dispara cuando una excepción es lanzada. | char *classname |
exception-caught | Se dispara cuando una excepción es capturada. | char *classname |
error | Se dispara cuando ocurre un error, sin importar el nivel deerror_reporting. | char *errormsg, char *request_file, intlineno |
Otras extensiones PHP pueden también tener otras sondas estáticas adicionales.
Para listar todas las sondas disponibles, inicie un proceso PHP y ejecute:
# dtrace -l
La salida será similar a:
ID PROVIDER MODULE FUNCTION NAME
[ . . . ]
4 php15271 php dtrace_compile_file compile-file-entry
5 php15271 php dtrace_compile_file compile-file-return
6 php15271 php zend_error error
7 php15271 php ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
8 php15271 php zend_throw_exception_internal exception-thrown
9 php15271 php dtrace_execute_ex execute-entry
10 php15271 php dtrace_execute_internal execute-entry
11 php15271 php dtrace_execute_ex execute-return
12 php15271 php dtrace_execute_internal execute-return
13 php15271 php dtrace_execute_ex function-entry
14 php15271 php dtrace_execute_ex function-return
15 php15271 php php_request_shutdown request-shutdown
16 php15271 php php_request_startup request-startup
La columna Proveedor consiste enphpy el id del proceso del proceso PHP que está ejecutandose.
Si el servidor web Apache está corriendo, el nombre del módulo será, por ejemplo,libphp5.so, y habría múltiples bloques de listado, uno por cada proceso Apache ejecutandose.
La columna Función se refiere los nombres internos de función de su implementación en C, donde cada proveedor está ubicado.
Si un proceso PHP no está ejecutandose, entonces ningún sondeo será mostrado.
Este ejemplo muestra los conceptos básicos del lenguaje de scripting DTrace D.
Ejemplo #1all_probes.dpara monitorizar todos los Śondeos Estáticos en PHP con DTrace
#!/usr/sbin/dtrace -Zs
#pragma D option quiet
php*:::compile-file-entry
{
printf("PHP compile-file-entry\n");
printf(" compile_file %s\n", copyinstr(arg0));
printf(" compile_file_translated %s\n", copyinstr(arg1));
}
php*:::compile-file-return
{
printf("PHP compile-file-return\n");
printf(" compile_file %s\n", copyinstr(arg0));
printf(" compile_file_translated %s\n", copyinstr(arg1));
}
php*:::error
{
printf("PHP error\n");
printf(" errormsg %s\n", copyinstr(arg0));
printf(" request_file %s\n", copyinstr(arg1));
printf(" lineno %d\n", (int)arg2);
}
php*:::exception-caught
{
printf("PHP exception-caught\n");
printf(" classname %s\n", copyinstr(arg0));
}
php*:::exception-thrown
{
printf("PHP exception-thrown\n");
printf(" classname %s\n", copyinstr(arg0));
}
php*:::execute-entry
{
printf("PHP execute-entry\n");
printf(" request_file %s\n", copyinstr(arg0));
printf(" lineno %d\n", (int)arg1);
}
php*:::execute-return
{
printf("PHP execute-return\n");
printf(" request_file %s\n", copyinstr(arg0));
printf(" lineno %d\n", (int)arg1);
}
php*:::function-entry
{
printf("PHP function-entry\n");
printf(" function_name %s\n", copyinstr(arg0));
printf(" request_file %s\n", copyinstr(arg1));
printf(" lineno %d\n", (int)arg2);
printf(" classname %s\n", copyinstr(arg3));
printf(" scope %s\n", copyinstr(arg4));
}
php*:::function-return
{
printf("PHP function-return\n");
printf(" function_name %s\n", copyinstr(arg0));
printf(" request_file %s\n", copyinstr(arg1));
printf(" lineno %d\n", (int)arg2);
printf(" classname %s\n", copyinstr(arg3));
printf(" scope %s\n", copyinstr(arg4));
}
php*:::request-shutdown
{
printf("PHP request-shutdown\n");
printf(" file %s\n", copyinstr(arg0));
printf(" request_uri %s\n", copyinstr(arg1));
printf(" request_method %s\n", copyinstr(arg2));
}
php*:::request-startup
{
printf("PHP request-startup\n");
printf(" file %s\n", copyinstr(arg0));
printf(" request_uri %s\n", copyinstr(arg1));
printf(" request_method %s\n", copyinstr(arg2));
}
Este script utiliza la opción-Zendtrace, permitiendo que se ejecute aún cuando no hay procesos PHP ejecutandose. Si esta opción se hubiese omitido el script hubiese terminado inmediatamente porque no sabría que los sondeos a ser monitorizados realmente son válidos.
Este script rastrea todas las sondas estáticas del núcleo de PHP y puntos de muestreo a lo largo de la duración de un script PHP que esté corriendo:
# ./all_probes.d
Ejecuta un script o aplicación PHP. El script D de monitorización mostrará los argumentos de cada sondeo según vayan sucediendo.
Cuando la monitorización está completada, el script D puede ser terminado con^C.
En máquinas con múltiples-CPU el orden de los sondeos podría no aparecer secuencialmente. Esto depende de en que CPU fue procesado, y como los hilos se mueven a través de las CPUs. Mostrar la fecha y hora del sondeo ayudará a reducir la confusión, por ejemplo:
php*:::function-entry
{
printf("%lld: PHP function-entry ", walltimestamp);
[ . . .]
}
En algunas distribuciones Linux, la utilidad de rastreo SystemTap puede ser usada para rastrear sondas estáticas en PHP. Esto está disponible con PHP 5.4.20 y PHP 5.5.
Instalar el paquete de desarrollo SD de SystemTap:
# yum install systemtap-sdt-devel
Instalar PHP con los sondeos de DTrace habilitados:
# ./configure --enable-dtrace ... # make
Los sondeos estáticos en PHP pueden ser listados usandostap:
# stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'
Esto produce la salida:
process("sapi/cli/php").provider("php").mark("compile__file__entry")
process("sapi/cli/php").provider("php").mark("compile__file__return")
process("sapi/cli/php").provider("php").mark("error")
process("sapi/cli/php").provider("php").mark("exception__caught")
process("sapi/cli/php").provider("php").mark("exception__thrown")
process("sapi/cli/php").provider("php").mark("execute__entry")
process("sapi/cli/php").provider("php").mark("execute__return")
process("sapi/cli/php").provider("php").mark("function__entry")
process("sapi/cli/php").provider("php").mark("function__return")
process("sapi/cli/php").provider("php").mark("request__shutdown")
process("sapi/cli/php").provider("php").mark("request__startup")
Ejemplo #1all_probes.stppara monitorizar todas los Sondeos Estáticos de PHP con SystemTap
probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
printf("Probe compile__file__entry\n");
printf(" compile_file %s\n", user_string($arg1));
printf(" compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
printf("Probe compile__file__return\n");
printf(" compile_file %s\n", user_string($arg1));
printf(" compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("error") {
printf("Probe error\n");
printf(" errormsg %s\n", user_string($arg1));
printf(" request_file %s\n", user_string($arg2));
printf(" lineno %d\n", $arg3);
}
probe process("sapi/cli/php").provider("php").mark("exception__caught") {
printf("Probe exception__caught\n");
printf(" classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
printf("Probe exception__thrown\n");
printf(" classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("execute__entry") {
printf("Probe execute__entry\n");
printf(" request_file %s\n", user_string($arg1));
printf(" lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("execute__return") {
printf("Probe execute__return\n");
printf(" request_file %s\n", user_string($arg1));
printf(" lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("function__entry") {
printf("Probe function__entry\n");
printf(" function_name %s\n", user_string($arg1));
printf(" request_file %s\n", user_string($arg2));
printf(" lineno %d\n", $arg3);
printf(" classname %s\n", user_string($arg4));
printf(" scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("function__return") {
printf("Probe function__return: %s\n", user_string($arg1));
printf(" function_name %s\n", user_string($arg1));
printf(" request_file %s\n", user_string($arg2));
printf(" lineno %d\n", $arg3);
printf(" classname %s\n", user_string($arg4));
printf(" scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
printf("Probe request__shutdown\n");
printf(" file %s\n", user_string($arg1));
printf(" request_uri %s\n", user_string($arg2));
printf(" request_method %s\n", user_string($arg3));
}
probe process("sapi/cli/php").provider("php").mark("request__startup") {
printf("Probe request__startup\n");
printf(" file %s\n", user_string($arg1));
printf(" request_uri %s\n", user_string($arg2));
printf(" request_method %s\n", user_string($arg3));
}El script anterior rastreará todas las sondas estáticas del núcleo de PHP y puntos de muestreo a lo largo de la duración de un script PHP que esté corriendo:
# stap -c 'sapi/cli/php test.php' all_probes.stp
Ver tambiénCategorización de Extensiones.
APCu es APC despojado del almacenamiento en caché del código de operación.
La primera base de código de APCu tenía la versión 4.0.0, y se bifurcó de la rama principal de APC en ese momento.
El soporte para PHP 7 está disponible a partir de APCu 5.0.0.
APCu puede proporcionar un modo de compatibilidad, de modo que pueda proporcionar una caída en reemplazo para las partes aplicables de APC.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
Si se requiere retrocompatibilidad con las partes de APC aplicables APCu debe configurarse con la opción --enable-apcu-bc.
PHP 7 tiene un módulo aparte (» apc.so) para la retrocompatibilidad con APC.
En el modo de retrocompatibilidad, APCu registra las funciones de APC aplicables con prototipos retrocompatibles.
Si una función de APC aceptabacache_type, la ignora simplemente la versión retrocompatible, and omitted from the prototype for the APCu version.
Nota:En Windows, APC necesita una ruta temporal donde ubicarse, y debe ser escribible por el servidor web. Comprueba las variables de entorno TMP, TEMP y USERPROFILE, en este orden, y finalmente intenta el directorio WINDOWS si ninguno de los anteriores está establecido.
Nota:Para detalles de implementación más profundos y altamente téctino, veáse el» fichero TECHNOTES porporcionado por el desarrollador.
Los ficheros fuentes de APCu se pueden encontrar» aquí.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
Although the default APCu settings are fine for many installations, serious users should consider tuning the following parameters.
There is one decision to be made configuring APCu. How much memory is going to be allocated to APCu. The ini directive that controls this isapc.shm_sizeRead the sections on this carefully below.
Once the server is running, theapc.phpscript that is bundled with the extension should be copied somewhere into the docroot and viewed with a browser as it provides a detailed analysis of the internal workings of APCu. If GD is enabled in PHP, it will even display some interesting graphs.
If APCu is working, theCache full countnumber (on the left) will display the number of times the cache has reached maximum capacity and has had to evict entries to free up memory. During eviction, ifapc.ttlwas specified, APCu will first attempt to remove expired entries, i.e. entries whose TTL has either expired, or entries that have no TTL set and haven't been accessed in the lastapc.ttlseconds. Ifapc.ttlwas not set, or removing expired entries did not free up enough space, APCu will clear the entire cache.
The number of evictions should be minimal in a well-configured cache. If the cache is constantly being filled, and thusly forcefully freed, the resulting churning will have disparaging effects on script performance. The easiest way to minimize this number is to allocate more memory for APCu.
When APCu is compiled with mmap support (Memory Mapping), it will use only one memory segment, unlike when APCu is built with SHM (SysV Shared Memory) support that uses multiple memory segments. MMAP does not have a maximum limit like SHM does in/proc/sys/kernel/shmmax. In general MMAP support is recommended because it will reclaim the memory faster when the webserver is restarted and all in all reduces memory allocation impact at startup.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| apc.enabled | "1" | PHP_INI_SYSTEM | |
| apc.shm_segments | "1" | PHP_INI_SYSTEM | |
| apc.shm_size | "32M" | PHP_INI_SYSTEM | |
| apc.entries_hint | "4096" | PHP_INI_SYSTEM | |
| apc.ttl | "0" | PHP_INI_SYSTEM | |
| apc.gc_ttl | "3600" | PHP_INI_SYSTEM | |
| apc.mmap_file_mask | NULL | PHP_INI_SYSTEM | |
| apc.slam_defense | "1" | PHP_INI_SYSTEM | |
| apc.enable_cli | "0" | PHP_INI_SYSTEM | |
| apc.use_request_time | "0" | PHP_INI_ALL | Prior to APCu 5.1.19, the default was "1". |
| apc.serializer | "php" | PHP_INI_SYSTEM | Prior to APCu 5.1.15, the default was "default". |
| apc.coredump_unmap | "0" | PHP_INI_SYSTEM | |
| apc.preload_path | NULL | PHP_INI_SYSTEM |
He aquí una breve explicación de las directivas de configuración.
apc.enabledboolapc.enabledcan be set to 0 to disable APC. This is primarily useful when APC is statically compiled into PHP, since there is no other way to disable it (when compiled as a DSO, theextensionline inphp.inican just be commented-out).
apc.shm_segmentsintThe number of shared memory segments to allocate for the compiler cache. If APC is running out of shared memory butapc.shm_sizeis set as high as the system allows, raising this value might prevent APC from exhausting its memory.
apc.shm_sizestringThe size of each shared memory segment given by a shorthand notation as described inthis FAQ. By default, some systems (including most BSD variants) have very low limits on the size of a shared memory segment.
apc.entries_hintintA "hint" about the number of distinct variables that might be stored. Set to zero or omit if not sure.
apc.ttlintConsider cache entries without an explicit TTL to be expired if they have not been accessed in this many seconds. Effectively, this allows such entries to be removed opportunistically during a cache insert, or prior to a full expunge. Note that because removal is opportunistic, entries can still be readable even if they are older thanapc.ttlseconds. This setting has no effect on cache entries that have an explicit TTL specified.
apc.gc_ttlintThe number of seconds that a cache entry may remain on the garbage-collection list. This value provides a fail-safe in the event that a server process dies while executing a cached source file; if that source file is modified, the memory allocated for the old version will not be reclaimed until this TTL reached. Set to zero to disable this feature.
apc.mmap_file_maskstringIf compiled with MMAP support by using--enable-mmapthis is the mktemp-style file_mask to pass to the mmap module for determining whether your mmap'ed memory region is going to be file-backed or shared memory backed. For straight file-backed mmap, set it to something like/tmp/apc.XXXXXX(exactly 6Xs). To use POSIX-style shm_open/mmap put a.shmsomewhere in your mask. e.g./apc.shm.XXXXXXYou can also set it to/dev/zeroto use your kernel's/dev/zerointerface to anonymous mmap'ed memory. Leaving it undefined will force an anonymous mmap.
apc.slam_defenseintOn very busy servers whenever you start the server or modify files you can create a race of many processes all trying to cache the same file at the same time. This option sets the percentage of processes that will skip trying to cache an uncached file. Or think of it as the probability of a single process to skip caching. For example, settingapc.slam_defenseto75would mean that there is a 75% chance that the process will not cache an uncached file. So, the higher the setting the greater the defense against cache slams. Setting this to0disables this feature.
apc.enable_cliintMostly for testing and debugging. Setting this enables APC for the CLI version of PHP. Under normal circumstances, it is not ideal to create, populate and destroy the APC cache on every CLI request, but for various test scenarios it is useful to be able to enable APC for the CLI version of PHP easily.
apc.serializerstringUsed to configure APC to use a third party serializer.
apc.coredump_unmapboolEnables APC handling of signals, such as SIGSEGV, that write core files when signaled. When these signals are received, APC will attempt to unmap the shared memory segment in order to exclude it from the core file. This setting may improve system stability when fatal signals are received and a large APC shared memory segment is configured.
This feature is potentially dangerous. Unmapping the shared memory segment in a fatal signal handler may cause undefined behaviour if a fatal error occurs.
Nota:
Although some kernels may provide a facility to ignore various types of shared memory when generating a core dump file, these implementations may also ignore important shared memory segments such as the Apache scoreboard.
apc.preload_pathstringOptionally, set a path to the directory that APC will load cache data at startup.
apc.use_request_timeboolUse theSAPIrequest start time forTTL.
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
APC_ITER_ALL(integer)APC_ITER_ATIME(integer)APC_ITER_CTIME(integer)APC_ITER_DEVICE(integer)APC_ITER_DTIME(integer)APC_ITER_FILENAME(integer)APC_ITER_INODE(integer)APC_ITER_KEY(integer)APC_ITER_MD5(integer)APC_ITER_MEM_SIZE(integer)APC_ITER_MTIME(integer)APC_ITER_NONE(integer)APC_ITER_NUM_HITS(integer)APC_ITER_REFCOUNT(integer)APC_ITER_TTL(integer)APC_ITER_TYPE(integer)APC_ITER_VALUE(integer)APC_LIST_ACTIVE(integer)APC_LIST_DELETED(integer)(PECL apcu >= 4.0.0)
apcu_add—Cache a new variable in the data store
Caches a variable in the data store, only if it's not already stored.
Nota:Unlike many other mechanisms in PHP, variables stored usingapcu_add()will persist between requests (until the value is removed from the cache).
keyStore the variable using this name.keys are cache-unique, so attempting to useapcu_add()to store data with a key that already exists will not overwrite the existing data, and will instead returnfalse. (This is the only difference betweenapcu_add()andapcu_store().)
varThe variable to store
ttlTime To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
valuesNames in key, variables in value.
Returns TRUE if something has effectively been added into the cache, FALSE otherwise. Second syntax returns array with error keys.
Ejemplo #1 Aapcu_add()example
<?php
$bar='BAR';
apcu_add('foo',$bar);
var_dump(apcu_fetch('foo'));
echo"\n";
$bar='NEVER GETS SET';
apcu_add('foo',$bar);
var_dump(apcu_fetch('foo'));
echo"\n";
?>El resultado del ejemplo sería:
string(3) "BAR" string(3) "BAR"
(PECL apcu >= 4.0.0)
apcu_cache_info—Recupera la información almacenada en la memoria APCu
$limited=false):arrayRecupera la información almacenada y los metadatos del almacén de datos de la APC.
limitedSi el parámetrolimitedestrue, el valor devuelto excluirá la lista individual de entradas de la memoria caché. Esto es útil cuando se intentan optimizar las llamadas para la recopilación de estadísticas.
Array de datos en caché (y metadatos) ofalseen caso de error
Nota:apcu_cache_info()hará una advertencia si no puede recuperar los datos de la caché del APC. Esto suele ocurrir cuando el APC no está activado.
| Versión | Descripción |
|---|---|
| 3.0.11 | El parámetrolimitedfué introducido. |
| 3.0.16 | La opción "filehits" para el parámetrocache_typefué introducido. |
Ejemplo #1 Un ejemplo deapcu_cache_info()
<?php
print_r(apcu_cache_info());
?>El resultado del ejemplo sería algo similar a:
Array
(
[num_slots] => 2000
[ttl] => 0
[num_hits] => 9
[num_misses] => 3
[start_time] => 1123958803
[cache_list] => Array
(
[0] => Array
(
[filename] => /path/to/apcu_test.php
[device] => 29954
[inode] => 1130511
[type] => file
[num_hits] => 1
[mtime] => 1123960686
[creation_time] => 1123960696
[deletion_time] => 0
[access_time] => 1123962864
[ref_count] => 1
[mem_size] => 677
)
[1] => Array (...iterates for each cached file)
)
(PECL apcu >= 4.0.0)
apcu_cas—Actualiza un valor antiguo con un nuevo valor
$key,int$old,int$new):boolapcu_cas()actualiza un valor entero ya existente si el parámetrooldcoincide el valor almacenado actualmente con el valor del parámetronew.
keyLa clave del valor que se está actualizando.
oldEl valor antiguo (el valor actualmente almacenado).
newEl nuevo valor al que actualizar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo deapcu_cas()
<?php
apcu_store('foobar',2);
echo'$foobar = 2',PHP_EOL;
echo'$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar',1,2) ?'ok':'fail'),PHP_EOL;
echo'$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar',2,1) ?'ok':'fail'),PHP_EOL;
echo'$foobar = ',apcu_fetch('foobar'),PHP_EOL;
echo'$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar',1,2) ?'ok':'fail'),PHP_EOL;
apcu_store('perfection','xyz');
echo'$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection',2,1) ?'ok':'epic fail'),PHP_EOL;
echo'$foobar = ',apcu_fetch('foobar'),PHP_EOL;
?>El resultado del ejemplo sería algo similar a:
$foobar = 2 $foobar == 1 ? 2 : 1 = fail $foobar == 2 ? 1 : 2 = ok $foobar = 1 $f__bar == 1 ? 2 : 1 = fail $perfection == 2 ? 1 : 2 = epic fail $foobar = 1
(PECL apcu >= 4.0.0)
apcu_clear_cache—Limpia el caché del APCu
Limpia el caché.
Esta función no tiene parámetros.
Devuelve siempretrue
(PECL apcu >= 4.0.0)
apcu_dec—Disminuir un número almacenado
$key,$step= 1,&$success= ?,$ttl= 0Disminuye un valor entero almacenado.
keyLa clave de el valor a ser disminuido.
stepEl paso, o valor a disminuir.
successOpcionalmente pasa el valor booleano en caso de éxito o en caso de error a esta variable referenciada.
ttlTTL para usar si la operación inserta un nuevo valor (en lugar de disminuir uno existente).
Devuelve el valor actual del valor de las claves (key) en caso de éxito, ofalseen caso de error
| Versión | Descripción |
|---|---|
| 5.1.12 | El parámetrottlfué añadido. |
Ejemplo #1 Ejemplo deapcu_dec()
<?php
echo"Let's do something with success",PHP_EOL;
apcu_store('anumber',42);
echoapcu_fetch('anumber'),PHP_EOL;
echoapcu_dec('anumber'),PHP_EOL;
echoapcu_dec('anumber',10),PHP_EOL;
echoapcu_dec('anumber',10,$success),PHP_EOL;
var_dump($success);
echo"Now, let's fail",PHP_EOL,PHP_EOL;
apcu_store('astring','foo');
$ret=apcu_dec('astring',1,$fail);
var_dump($ret);
var_dump($fail);
?>El resultado del ejemplo sería algo similar a:
Let's do something with success 42 41 31 21 bool(true) Now, let's fail bool(false) bool(false)
(PECL apcu >= 4.0.0)
apcu_delete—Elimina una variable almacenada en caché
keyUna clave (key) empleada para almacenar el valor como unstringpara una única clave, o como unarrayde strings para varias claves, o como unobjectAPCUIterator.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Un ejemplo deapcu_delete()
<?php
$bar='BAR';
apcu_store('foo',$bar);
apcu_delete('foo');
// obviamente, esto no es útil de esta forma
// Alternativamente, borrar varias claves.
apcu_delete(['foo','bar','baz']);
// O utilizar un Iterator con una expresión regular.
apcu_delete(newAPCUIterator('#^myprefix_#'));
?>(PECL apcu >= 4.0.3)
apcu_enabled—Si el APCu es utilizable en el entorno actual
Devuelve si el APCu es utilizable en el entorno actual.
Esta función no tiene parámetros.
Devuelvetrueuando el APCu es utilizable en el entorno actual,falseen caso contrario.
(PECL apcu >= 5.1.0)
apcu_entry—Atomically fetch or generate a cache entry
Atomically attempts to findkeyin the cache, if it cannot be foundgeneratoris called, passingkeyas the only argument. The return value of the call is then cached with the optionally specifiedttl, and returned.
Nota:When control entersapcu_entry()the lock for the cache is acquired exclusively, it is released when control leavesapcu_entry(): In effect, this turns the body of
generatorinto a critical section, disallowing two processes from executing the same code paths concurrently. In addition, it prohibits the concurrent execution of any other APCu functions, since they will acquire the same lock.
The only APCu function that can be called safely bygeneratorisapcu_entry().
keyIdentity of cache entry
generatorA callable that acceptskeyas the only argument and returns the value to cache.
ttlTime To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
Returns the cached value
Ejemplo #1 Anapcu_entry()example
<?php
$config=apcu_entry("config", function($key) {
return [
"fruit"=>apcu_entry("config.fruit", function($key){
return [
"apples",
"pears"
];
}),
"people"=>apcu_entry("config.people", function($key){
return [
"bob",
"joe",
"niki"
];
})
];
});
var_dump($config);
?>El resultado del ejemplo sería:
array(2) {
["fruit"]=>
array(2) {
[0]=>
string(6) "apples"
[1]=>
string(5) "pears"
}
["people"]=>
array(3) {
[0]=>
string(3) "bob"
[1]=>
string(3) "joe"
[2]=>
string(4) "niki"
}
}
(PECL apcu >= 4.0.0)
apcu_exists—Checks if entry exists
keysAstring, or anarrayof strings, that contain keys.
Returnstrueif the key exists, otherwisefalseOr if anarraywas passed tokeys, then an array is returned that contains all existing keys, or an empty array if none exist.
Ejemplo #1apcu_exists()example
<?php
$fruit='apple';
$veggie='carrot';
apcu_store('foo',$fruit);
apcu_store('bar',$veggie);
if (apcu_exists('foo')) {
echo"Foo exists: ";
echoapcu_fetch('foo');
} else {
echo"Foo does not exist";
}
echoPHP_EOL;
if (apcu_exists('baz')) {
echo"Baz exists.";
} else {
echo"Baz does not exist";
}
echoPHP_EOL;
$ret=apcu_exists(array('foo','donotexist','bar'));
var_dump($ret);
?>El resultado del ejemplo sería algo similar a:
Foo exists: apple
Baz does not exist
array(2) {
["foo"]=>
bool(true)
["bar"]=>
bool(true)
}
(PECL apcu >= 4.0.0)
apcu_fetch—Fetch a stored variable from the cache
keyThekeyused to store the value (withapcu_store()). If an array is passed then each element is fetched and returned.
successSet totruein success andfalsein failure.
The stored variable or array of variables on success;falseon failure
| Versión | Descripción |
|---|---|
| PECL apcu 3.0.17 | Thesuccessparameter was added. |
Ejemplo #1 Aapcu_fetch()example
<?php
$bar='BAR';
apcu_store('foo',$bar);
var_dump(apcu_fetch('foo'));
?>El resultado del ejemplo sería:
string(3) "BAR"
(PECL apcu >= 4.0.0)
apcu_inc—Increase a stored number
$key,$step= 1,&$success= ?,$ttl= 0Increases a stored number.
keyThe key of the value being increased.
stepThe step, or value to increase.
successOptionally pass the success or fail boolean value to this referenced variable.
ttlTTL to use if the operation inserts a new value (rather than incrementing an existing one).
Returns the current value ofkey's value on success, ofalseen caso de error
Ejemplo #1apcu_inc()example
<?php
echo"Let's do something with success",PHP_EOL;
apcu_store('anumber',42);
echoapcu_fetch('anumber'),PHP_EOL;
echoapcu_inc('anumber'),PHP_EOL;
echoapcu_inc('anumber',10),PHP_EOL;
echoapcu_inc('anumber',10,$success),PHP_EOL;
var_dump($success);
echo"Now, let's fail",PHP_EOL,PHP_EOL;
apcu_store('astring','foo');
$ret=apcu_inc('astring',1,$fail);
var_dump($ret);
var_dump($fail);
?>El resultado del ejemplo sería algo similar a:
Let's do something with success 42 43 53 63 bool(true) Now, let's fail bool(false) bool(false)
(No version information available, might only be in Git)
apcu_key_info—Get detailed information about the cache key
$key):?arrayGet detailed information about the cache key
keyGet detailed information about the cache key
An array containing the detailed information about the cache key, ornullif the key does not exist.
Ejemplo #1 Aapcu_key_info()example
<?php
apcu_add('a','b');
var_dump(apcu_key_info('a'));
?>El resultado del ejemplo sería:
array(7) {
["hits"]=>
int(0)
["access_time"]=>
int(1606701783)
["mtime"]=>
int(1606701783)
["creation_time"]=>
int(1606701783)
["deletion_time"]=>
int(0)
["ttl"]=>
int(0)
["refs"]=>
int(0)
}
(PECL apcu >= 4.0.0)
apcu_sma_info—Retrieves APCu Shared Memory Allocation information
$limited=false):array|falseRetrieves APCu Shared Memory Allocation information.
limitedWhen set tofalse(default)apcu_sma_info()will return a detailed information about each segment.
Array of Shared Memory Allocation data;falseon failure.
Ejemplo #1 Aapcu_sma_info()example
<?php
print_r(apcu_sma_info());
?>El resultado del ejemplo sería algo similar a:
Array
(
[num_seg] => 1
[seg_size] => 31457280
[avail_mem] => 31448408
[block_lists] => Array
(
[0] => Array
(
[0] => Array
(
[size] => 31448408
[offset] => 8864
)
)
)
)
(PECL apcu >= 4.0.0)
apcu_store—Cache a variable in the data store
Cache a variable in the data store.
Nota:Unlike many other mechanisms in PHP, variables stored usingapcu_store()will persist between requests (until the value is removed from the cache).
keyStore the variable using this name.keys are cache-unique, so storing a second value with the samekeywill overwrite the original value.
varThe variable to store
ttlTime To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
valuesNames in key, variables in value.
Devuelvetrueen caso de éxito ofalseen caso de error. Second syntax returns array with error keys.
Ejemplo #1 Aapcu_store()example
<?php
$bar='BAR';
apcu_store('foo',$bar);
var_dump(apcu_fetch('foo'));
?>El resultado del ejemplo sería:
string(3) "BAR"
(PECL apcu >= 5.0.0)
La claseAPCUIteratorhace más fácil iterar sobre grandes cachés de APCu. Esto es útil ya que permite iterar sobre grandes cachés en pasos, al mismo tiempo que captura un número definido de entradas por instancia de bloqueo, por lo que libera los bloqueos de caché para otras actividades en lugar de mantener todo el caché para obtener 100 entradas (el valor por defecto). Además, utilizar comparación por expresiones regulares es más eficiente ya que se ha movido al nivel de C.
$search=null,$format= APC_ITER_ALL,$chunk_size= 100,$list= APC_LIST_ACTIVE(PECL apcu >= 5.0.0)
APCUIterator::__construct—Construye un objeto iterador APCUIterator
$search=null,$format= APC_ITER_ALL,$chunk_size= 100,$list= APC_LIST_ACTIVEConstruye unAPCUIteratorobject.
searchUna expresión regular delPCREque coincide con los nombres clave de la APCu, ya sea comostringpara una sola expresión regular, o como unarrayde expresiones regular. O, opcionalmente pasar ennullpara saltarse la búsqueda.
formatEl formato deseado, tal como está configurado con una o más de las constantesAPC_ITER_*.
chunk_sizeEl tamaño del fragmento. Debe ser un valor mayor que 0. El valor por defecto es 100.
listEl tipo de lista. O bien pasar enAPC_LIST_ACTIVEoAPC_LIST_DELETED.
UnAPCUIteratorobjecten caso de éxito, onullen caso de error.
Ejemplo #1 Un ejemplo deAPCUIterator::__construct()
<?php
foreach (newAPCUIterator('/^counter\./') as$counter) {
echo"$counter[key]:$counter[value]\n";
apc_dec($counter['key'],$counter['value']);
}
?>(PECL apcu >= 5.0.0)
APCUIterator::current—Obtener el elemento actual
Esta función no tiene parámetros.
Devuelve el elemento actual en caso de éxito, ofalsesi no hay más elementos o no existen, o en caso de error.
(PECL apcu >= 5.0.0)
APCUIterator::getTotalCount—Obtiene el conteo total
Obtener el conteo total.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
El conteo total.
(PECL apcu >= 5.0.0)
APCUIterator::getTotalHits—Obtener resultados totales de la memoria caché
Obtiene el número total de visitas a la memoria caché.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
El número de visitas en caso de éxito, ofalseen caso de error.
(PECL apcu >= 5.0.0)
APCUIterator::getTotalSize—Obtiene el tamaño total del caché
Obtiene el tamaño total del caché.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
El tamaño total del caché.
(PECL apcu >= 5.0.0)
APCUIterator::key—Obtiene la clave del iterador
Obtiene la clave del iterador actual.
Esta función no tiene parámetros.
Devuelve la clave en caso de éxito, ofalseen caso de error.
(PECL apcu >= 5.0.0)
APCUIterator::next—Mueve el puntero al siguiente elemento
Mueve el puntero del iterador al siguiente elemento.
Esta función no tiene parámetros.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL apcu >= 5.0.0)
APCUIterator::rewind—Rebobina el iterador
Rebobina el iterador hasta el primer elemento.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PECL apcu >= 5.0.0)
APCUIterator::valid—Comprueba si la posición actual es válida
Comprueba si la posición actual del iterador es válida.
Esta función no tiene parámetros.
Devuelvetruesi la posición actual del iterador es válida, en caso contrariofalse.
Componere(latin, English: compose)se dirige a los entornos de producción y proporciona una API para composición de las clases, parches y moldeado.
Componere\Definitionse utiliza para definir (o redefinir) una clase en tiempo de ejecución; La clase puede entonces registrarse, y en caso de redefinición reemplaza a la clase original durante todo el tiempo que la claseComponere\Definitionexista.
Componere\Patchse utiliza para cambiar la clase de una instancia específica de un objeto en tiempo de ejecución; Tras su aplicación, el parche permanecerá aplicado durante todo el tiempo que la claseComponere\Patchexista, y puede ser revertido explícitamente.
Componere\Las funciones de moldeado pueden moldear entre tipos compatibles definidos por el usuario; Donde compatible significaTypees sub o super al tipo deobject.
Se requiere Reflection
(Componere 2 >= 2.1.0)
Esta abstracta final representa una entrada de clase, y no debe ser usado por el programador.
(Componere 2 >= 2.1.0)
Componere\Abstract\Definition::addInterface—Añadir Interface
$interface):DefinitionImplementará la interface dada en la definición actual
interfaceEl nombre de una interface insensible a las mayúsculas y minúsculas
La definición actual
LanzaráRuntimeExceptionsiDefinitionse registró
(Componere 2 >= 2.1.0)
Componere\Abstract\Definition::addMethod—Añadir método
$name,\Componere\Method$method):DefinitionCreará o anulará un método en la definición actual.
nameEl nombre del método insensible a las mayúsculas y minúsculas
method\Componere\Methodque no se haya añadido previamente a otraDefinition
La Definition actual
LanzaráRuntimeExceptionsiDefinitionse registró
LanzaráRuntimeExceptionsi el método se añadió a otra definición
(Componere 2 >= 2.1.0)
Componere\Abstract\Definition::addTrait—Añadir rasgo
$trait):DefinitionUsará el rasgo dado para la definición actual
traitEl nombre del rasgo insensible a las mayúsculas y minúsculas
La definición actual
LanzaráRuntimeExceptionsiDefinitionse registró
(Componere 2 >= 2.1.0)
Componere\Abstract\Definition::getReflector—Reflection
Creará o devolverá una clase Reflection
Una clase Reflection para la definición actual (en caché)
(Componere 2 >= 2.1.0)
La clase Definition permite al programador construir y registrar un tipo en tiempo de ejecución.
En caso de que una Definition reemplace una clase existente, la clase existente será restaurada cuando la Definition sea destruida.
(Componere 2 >= 2.1.0)
Componere\Definition::__construct—Constructor Definition
$name)$name,string$parent)$name,array$interfaces)$name,string$parent,array$interfaces)nameUn nombre de clase insensible a las mayúsculas y minúsculas
parentUn nombre de clase insensible a las mayúsculas y minúsculas
interfacesUn array de nombres de clase insensibles a las mayúsculas y minúsculas
LanzaráInvalidArgumentExceptionsi se intenta reemplazar una clase interna
LanzaráInvalidArgumentExceptionsi se intenta sustituir una interface
LanzaráInvalidArgumentExceptionsi se intenta reemplazar un rasgo
LanzaráRuntimeExceptionsi una clase eninterfacesno se puede encontrar
LanzaráRuntimeExceptionsi una clase eninterfacesno es una interface
(Componere 2 >= 2.1.0)
Componere\Definition::addConstant—Añade constante
$name,\Componere\Value$value):DefinitionDeclarará una constante de clase en la definición actual
nameEl nombre de la constante que distingue entre mayúsculas y minúsculas
valueEl valor de la constante, no debe ser indefinido o estático
La definición actual
LanzaráRuntimeExceptionsiDefinitionfué registrado
LanzaráRuntimeExceptionsinameya está declarada como una constante
LanzaráRuntimeExceptionsivaluees estática
LanzaráRuntimeExceptionsivalueno está definida
(Componere 2 >= 2.1.0)
Componere\Definition::addProperty—Añade propiedad
$name,\Componere\Value$value):DefinitionDeclarará una propiedad de clase sobre la definición actual
nameEl nombre de la propiedad distingue mayúsculas y minúsculas
valueEl valor por omisión de la propiedad
La definición actual
LanzaráRuntimeExceptionsiDefinitionse registró
LanzaráRuntimeExceptionsinameya está declarada como una propiedad
(Componere 2 >= 2.1.0)
Componere\Definition::register—Registro
Registrará la Definition actual
LanzaráRuntimeExceptionsiDefinitionfué registrada
(Componere 2 >= 2.1.0)
Componere\Definition::isRegistered—Detección del estado
Deberá detectar el estado de registro de Definition
Devolverá true si Definition está registrada
(Componere 2 >= 2.1.0)
Componere\Definition::getClosure—Obtener Cierre
$name):\ClosureDevolverá un cierre para el método especificado por el nombre
nameEl nombre del método insensible a las mayúsculas y minúsculas
Un cierre vinculado al alcance correcto
LanzaráRuntimeExceptionsiDefinitionse registró
LanzaráRuntimeExceptionsinameno se pudo encontrar
(Componere 2 >= 2.1.0)
Componere\Definition::getClosures—Obtener Cierres
Devolverá un array de cierres
Devolverá todos los métodos como un array de objetos de cierre vinculados al alcance correcto
LanzaráRuntimeExceptionsiDefinitionse registró
(Componere 2 >= 2.1.0)
La clase Patch permite al programador cambiar el tipo de una instancia en tiempo de ejecución sin registrar una nueva Definition
Cuando se destruye un parche se revierte, de modo que los casos que fueron parcheados durante la vida del Parche son restaurados a su tipo formal.
(Componere 2 >= 2.1.0)
Componere\Patch::__construct—Constructor Patch
$instance)$instance,array$interfaces)instanceEl objetivo de este Patch
interfacesUn array de nombres de clase insensibles a las mayúsculas y minúsculas
LanzaráRuntimeExceptionsi una clase eninterfacesno se puede encontrar
LanzaráRuntimeExceptionsi una clase eninterfacesno es una interface
(Componere 2 >= 2.1.0)
Componere\Patch::apply—Aplicación
Aplicará el parche actual
(Componere 2 >= 2.1.0)
Componere\Patch::revert—Reversión
Revertirá el parche actual
(Componere 2 >= 2.1.0)
Componere\Patch::isApplied—Detección del estado
(Componere 2 >= 2.1.1)
Componere\Patch::derive—Derivación del parche
$instance):PatchDerivará unPatch(parche) para lainstance(instancia) dada
instanceEl objetivo del Parche derivado
Patch(parche) para lainstance(instancia) derivada delPatch(parche) actual
LanzaráInvalidArgumentExceptionsiinstanceno es compatible
(Componere 2 >= 2.1.0)
Componere\Patch::getClosure—Obtener Cierre
$name):\ClosureDevolverá un cierre para el método especificado por el nombre
nameEl nombre del método insensible a las mayúsculas y minúsculas
Un cierre vinculado al ámbito y objeto correctos
LanzaráRuntimeExceptionsinameno se pudo encontrar
(Componere 2 >= 2.1.0)
Componere\Patch::getClosures—Obtener Cierres
Devolverá un array de Cierres
Devolverá todos los métodos como un array de objetos de cierre unidos al ámbito y objeto correctos
(Componere 2 >= 2.1.0)
Un método representa una función con banderas de accesibilidad modificables
(Componere 2 >= 2.1.0)
Componere\Method::__construct—Constructor Method
$closure)closure(Componere 2 >= 2.1.0)
Componere\Method::setPrivate—Modificación de la accesibilidad
El método actual
LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente
(Componere 2 >= 2.1.0)
Componere\Method::setProtected—Modificación de la accesibilidad
El método actual
LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente
(Componere 2 >= 2.1.0)
Componere\Method::setStatic—Modificación de la accesibilidad
El método actual
(Componere 2 >= 2.1.0)
Componere\Method::getReflector—Reflection
Creará o devolverá un Método de Reflection
Un método de Reflection para el método actual (en caché)
(Componere 2 >= 2.1.0)
Una clase Value representa una variable PHP de todos los tipos, incluyendo las indefinidas
(Componere 2 >= 2.1.0)
Componere\Value::__construct—Constructor Value
$default= ?)defaultLanzaráInvalidArgumentExceptionsidefaultno tiene un valor adecuado
(Componere 2 >= 2.1.0)
Componere\Value::setPrivate—Modificación de la accesibilidad
El valor actual
LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente
(Componere 2 >= 2.1.0)
Componere\Value::setProtected—Modificación de la accesibilidad
El valor actual
LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente
(Componere 2 >= 2.1.0)
Componere\Value::setStatic—Modificación de la accesibilidad
El valor actual
(Componere 2 >= 2.1.0)
Componere\Value::isPrivate—Detección de accesibilidad
(Componere 2 >= 2.1.0)
Componere\Value::isProtected—Detección de accesibilidad
(Componere 2 >= 2.1.0)
Componere\Value::isStatic—Detección de accesibilidad
(Componere 2 >= 2.1.0)
Componere\Value::hasDefault—Interacción de Value
(Componere 2 >= 2.1.2)
Componere\cast—Moldeado
$type,$object):TypetypeUn tipo definido por el usuario
objectUn objeto con un tipo definido por el usuario compatible conType
Unobjectde tipoType, moldeado deobject
LanzaráInvalidArgumentExceptionsi el tipo deobjectes o se deriva de una clase interna
LanzaráInvalidArgumentExceptionsiTypees una interface
LanzaráInvalidArgumentExceptionsiTypees un rasgo
LanzaráInvalidArgumentExceptionsiTypees una abstracta
LanzaráInvalidArgumentExceptionsiTypeno es compatible con el tipo deobject
(Componere 2 >= 2.1.2)
Componere\cast_by_ref—Moldeado
$type,$object):TypeUn tipo definido por el usuario
objectUn objeto con un tipo definido por el usuario compatible conType
Unobjectde tipoType, moldeado deobject, donde los miembros son referencias a miembros deobject
LanzaráInvalidArgumentExceptionsi el tipo deobjectes o se deriva de una clase interna
LanzaráInvalidArgumentExceptionsiTypees una interface
LanzaráInvalidArgumentExceptionsiTypees un rasgo
LanzaráInvalidArgumentExceptionsiTypees una abstracta
LanzaráInvalidArgumentExceptionsiTypeno es compatible con el tipo deobject
Estas funciones se ocupan del manejo y registro de errores. Le permiten definir sus propias reglas de manejo de errores, así como modificar la manera en que los errores pueden ser registrados. Esto le permite cambiar y mejorar la notificación de errores para acomodarla a sus necesidades.
Con las funciones de registro se pueden enviar mensajes directamente a otras máquinas, a un e-mail (¡o un e-mail a un busca!), al registro del sistema, etc., por lo que puede registrar y monitorizar selectivamente las partes más importantes de sus aplicaciones y sitios web.
Las funciones de notificación de errores le permiten personalizar qué niveles y tipos de errores se dan, abarcando desde simples avisos hasta funciones personalizadas devueltas al originarse un error.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| error_reporting | NULL | PHP_INI_ALL | |
| display_errors | "1" | PHP_INI_ALL | |
| display_startup_errors | "0" | PHP_INI_ALL | |
| log_errors | "0" | PHP_INI_ALL | |
| log_errors_max_len | "1024" | PHP_INI_ALL | Disponible a partir de PHP 4.3.0. |
| ignore_repeated_errors | "0" | PHP_INI_ALL | Disponible a partir de PHP 4.3.0. |
| ignore_repeated_source | "0" | PHP_INI_ALL | Disponible a partir de PHP 4.3.0. |
| report_memleaks | "1" | PHP_INI_ALL | Disponible a partir de PHP 4.3.0. |
| track_errors | "0" | PHP_INI_ALL | |
| html_errors | "1" | PHP_INI_ALL | PHP_INI_SYSTEM en PHP <= 4.2.3. |
| xmlrpc_errors | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 4.1.0. |
| xmlrpc_error_number | "0" | PHP_INI_ALL | Disponible a partir de PHP 4.1.0. |
| docref_root | "" | PHP_INI_ALL | Disponible a partir de PHP 4.3.0. |
| docref_ext | "" | PHP_INI_ALL | Disponible a partir de PHP 4.3.2. |
| error_prepend_string | NULL | PHP_INI_ALL | |
| error_append_string | NULL | PHP_INI_ALL | |
| error_log | NULL | PHP_INI_ALL | |
| error_log_mode | 0o644 | PHP_INI_ALL | Disponible a partir de PHP 8.2.0 |
| syslog.facility | "LOG_USER" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.3.0. |
| syslog.filter | "no-ctrl" | PHP_INI_ALL | Disponible a partir de PHP 7.3.0. |
| syslog.ident | "php" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.3.0. |
He aquí una breve explicación de las directivas de configuración.
error_reportingintegerEstablece el nivel de notificación de errores. El parámetro es o bien un valor de tipo integer que representa un campo de bits, o bien constantes con nombre. Los niveles de error_reporting y las constantes están descritos enConstantes predefinidas, y enphp.ini. Para establecerlo en tiempo de ejecución, se ha de usar la funciónerror_reporting(). Vése también la directivadisplay_errors.
En PHP 5.3 o posterior, el valor predeterminado esE_ALL& ~E_NOTICE& ~E_STRICT& ~E_DEPRECATED. Este ajuste no muestra los niveles de errorE_NOTICE,E_STRICTyE_DEPRECATED. Quizás quiera mostrarlos durante el desarrollo. Antes de PHP 5.3.0, el valor predeterminado esE_ALL& ~E_NOTICE& ~E_STRICT. en PHP, el valor predeterminado esE_ALL& ~E_NOTICE.
Nota:
La habilitación de
E_NOTICEdurante el desarrollo tiene algunos beneficios. Para las depuración: los mensajes NOTICE avisarán de posibles errores en el código. Por ejemplo, se advierte del uso de valores no asignados. Es extremadamente útil para encontrar errartas y ahorrar tiempo en la depuración. Los mensajes NOTICE avisarán de un estilo malo. Por ejemplo,$arr[item]es mejor que sea escrito como$arr['item']ya que PHP intenta tratar"item"como una constante. Si no es una constante, PHP asume que es un índice de string del array.
Nota:
En PHP 5 está disponible el nuevo nivel de error
E_STRICT. Antes de PHP 5.4.0,E_STRICTno estaba incluido dentro deE_ALL, por lo que se teniía de habilitar explícitamente este tipo de nivel de error en PHP < 5.4.0. La habilitación deE_STRICTdurante el desarrollo tiene algunos beneficios. Los mensajes STRICT proporcionan sugerencias que pueden ayudar a asegurarse de la mejor interoperabilidad y la compatibilidad hacia delante del código. Estos mensajes pueden incluir cosas como llamar a métodos no estáticos de forma estática, definir propiedades en una definición de clase compatible mientras se definió en un trait usado, y antes de PHP 5.3, algunas características obsoletas emitirían erroresE_STRICTcomo asignar objetos por referencias durante la instanciación.
Nota:Constantes de PHP fuera de PHP
El uso de constantes de PHP fuera de PHP, como enhttpd.conf, no tiene un propósito útil, por lo que, en tales casos, se requerirán los valores de tipointeger. Y ya que se añadirán más niveles de error en el futuro, el valor máximo (para
E_ALL) cambiará igualmente. Por lo que, en lugar deE_ALLse ha de considerar el uso de un valor grande para cubrir todos los campos de bits desde la actualidad hasta bien entrado en el futuro, un valor numérico como2147483647(incluye todos los errores, no sóloE_ALL).
display_errorsstringDetermina si los errores deberían ser impresos en pantalla como parte de la salida o si deberían ocultarse al usuario.
El valor"stderr"envía los errores astderren vez de astdout. Este valor está disponible a partir de PHP 5.2.4. En versiones anteriores esta directiva era de tipoboolean.
Nota:
Ésta es una característica para ayudar al desarrollo y nunca debería usarse en sistemas de producción (p.ej. en sistemas conectados a internet).
Nota:
Aunque display_errors puede ser establecido en tiempo de ejecución (conini_set()), no tendrá ningún efecto si el script tiene errores fatales. Esto es debido a que la acción deseada en tiempo de ejecución no se ejecuta.
display_startup_errorsbooleanIncluso cuando display_errors está activado, los errores que ocurren durante la secuencia de arranque de PHP no se muestran. Se recomienda encarecidamente mantener desactivado display_startup_errors, excepto para la depuración.
log_errorsbooleanIndica si los mensajes de error del script deberían de registrarse en el registro del servidor o enerror_log. Esta opción es, por lo tanto, específica para servidores.
Nota:
Se aconseja encarecidamente usar el registro de errores en lugar de mostrar los errores en sitios web de producción.
log_errors_max_lenintegerEstablece la longitud máxima de log_errors en bytes. Enerror_logse añade información acerca del origen. El valor predeterminado es 1024, y 0 permite no aplicar ninguna longitud máxima en absoluto. Esta longitud se aplica a los errores registrados, a los errores mostrados y también a$php_errormsg, pero no a las funciones llamadas explícitamente tal comeerror_log().
Cuando se usa uninteger, el valor del mismo es medido en bytes. También se puede usar la notación reducida, tal como se describe enesta FAQ.ignore_repeated_errorsbooleanNo registra mensajes repetidos. Los mensajes repetidos deben ocurrir en la misma línea del mismo fichero a menos queignore_repeated_sourceesté establecido a true.
ignore_repeated_sourcebooleanIgnora el origen del mensaje cuando se ignoran mensajes repetidos. Cuando este ajuste está activado (On) no se registrarán errores con mensajes repetidos de diferentes ficheros o líneas del código fuente.
report_memleaksbooleanSi este parámetro está activado (On), que es lo predeterminado, mostrará un informe de pérdidas de memoria detectado por el gestor de memoria Zend. Este informe será enviado a stderr en las plataformas Posix. En Windows, será enviado al depurador usando OutputDebugString(), y podrá ser visto con herramientas como» DbgView. Este parámetro solo tiene efecto en una versión de depuración, y si error_reporting incluyeE_WARNINGen la lista permitida.
track_errorsbooleanSi está habilitado, el último mensaje de error siempre estará presente en la variable$php_errormsg.
html_errorsbooleanSi se habilita, los mensajes de error incluirán etiquetas HTML. El formato para los errores HTML produce mensajes clicables que dirigen al usuario a una página que describe el error o función que causó el error. Estas referencias se ven afectadas pordocref_rootydocref_ext.
Si se inhabilita, el mensaje de error será solamente texto plano.
xmlrpc_errorsbooleanSi se habilita, se desactiva el reporte de errores normal y se formatean los errores como mensajes de error XML-RPC.
xmlrpc_error_numberintegerUsado como el valor del elemento faultCode de XML-RPC.
docref_rootstringEl nuevo formato de error contiene una referencia a una página que describe el error o a la función que causa el error. En caso de páginas de manual, se puede descargar el manual en su idioma y establecer esta directiva ini al URL de su copia local. Si a su copia local del manual se puede llegar mediante"/manual/"puede usar simplementedocref_root=/manual/. Además tiene que establecer docref_ext para que coincida con las extensiones de fichero de su copiadocref_ext=.html. Es posible usar referencias externas. Por ejemplo, se puede usardocref_root=http://manual/en/odocref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"
La mayoría de las veces será necesario que el valor de docref_root termine con una barra"/". Sin embargo, veáse el segundo ejemplo de antes, el cuál ni la tiene ni la necesita.
Nota:
Esta es una característica para ayudar al desarrollo, ya que hace más fácil buscar una descripción de una función. Sin embargo, nunca debería usarse en sistemas de producción (p.ej. en sistemas conectados a internet).
docref_extstringVéasedocref_root.
Nota:
El valor de docref_ext debe comenzar con un punto
".".
error_prepend_stringstringString a imprimir antes de un mensaje de error.
error_append_stringstringString a imprimir después de un mensaje de error.
error_logstringNombre del fichero donde los errores del script deberían ser registrados. El fichero debería ser modificable por el usuario del servidor web. Si se usa el valor especialsyslog, los errores son enviados en su lugar al registro del sistema. En Unix, esto quiere decir syslog(3) y en Windows quiere decir el registro de sucesos. Véase también:syslog(). Si esta directiva no está establecida, los errores se enviarán al registro de error de la SAPI. Por ejemplo, un registro de error en Apache ostderren CLI. Véase tambiénerror_log().
error_log_modeintFile mode for the file described set inerror_log.
syslog.facilitystringEspecifica el tipo de programa que está registrando el mensaje. Solamente efectivo sierror_logse establece a "syslog".
syslog.filterstringEspecifica el tipo de filtro a aplicar a los mensajes registrados. Los caracteres pertimitos se pasan sin modificar; los demás se escriben en su representación hexadecimal prefijados con\x. Existen tres tipos de filtro permitidos:
all– todos los caracteresno-ctrl– todos los caracteres excepto los de controlascii– todos los caracteres ASCII imprimibles yNLsyslog.identstringEspecifica la cadena de sangrado que antecede a todo mensaje. Solamente efectivo sierror_logse establece a "syslog".
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.
Nota:Se pueden usar estos nombres de constantes enphp.inipero no fuera de PHP, como enhttpd.conf, donde se deberían usar en su lugar valores de máscara de bits.
| Valor | Constante | Descripción | Nota |
|---|---|---|---|
| 1 | E_ERROR(integer) | Errores Fatales en tiempo de ejecución. Éstos indican errores que no se pueden recuperar, tales como un problema de asignación de memoria. La ejecución del script se interrumpe. | |
| 2 | E_WARNING(integer) | Advertencias en tiempo de ejecución (errores no fatales). La ejecución del script no se interrumpe. | |
| 4 | E_PARSE(integer) | Errores de análisis en tiempo de compilación. Los errores de análisis deberían ser generados únicamente por el analizador. | |
| 8 | E_NOTICE(integer) | Avisos en tiempo de ejecución. Indican que el script encontró algo que podría señalar un error, pero que también podría ocurrir en el curso normal al ejecutar un script. | |
| 16 | E_CORE_ERROR(integer) | Errores fatales que ocurren durante el arranque incial de PHP. Son como unE_ERROR, excepto que son generados por el núcleo de PHP. | |
| 32 | E_CORE_WARNING(integer) | Advertencias (errores no fatales) que ocurren durante el arranque inicial de PHP. Son como unE_WARNING, excepto que son generados por el núcleo de PHP. | |
| 64 | E_COMPILE_ERROR(integer) | Errores fatales en tiempo de compilación. Son como unE_ERROR, excepto que son generados por Motor de Script Zend. | |
| 128 | E_COMPILE_WARNING(integer) | Advertencias en tiempo de compilación (errores no fatales). Son como unE_WARNING, excepto que son generados por Motor de Script Zend. | |
| 256 | E_USER_ERROR(integer) | Mensaje de error generado por el usuario. Es como unE_ERROR, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). | |
| 512 | E_USER_WARNING(integer) | Mensaje de advertencia generado por el usuario. Es como unE_WARNING, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). | |
| 1024 | E_USER_NOTICE(integer) | Mensaje de aviso generado por el usuario. Es como unE_NOTICE, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). | |
| 2048 | E_STRICT(integer) | Habilítelo para que PHP sugiera cambios en su código, lo que asegurará la mejor interoperabilidad y compatibilidad con versiones posteriores de PHP de su código. | Desde PHP 5 pero no incluidoenE_ALLhasta PHP 5.4.0 |
| 4096 | E_RECOVERABLE_ERROR(integer) | Error fatal capturable. Indica que ocurrió un error probablemente peligroso, pero no dejó al Motor en un estado inestable. Si no se captura el error mediante un gestor definido por el usuario (vea tambiénset_error_handler()), la aplicación se abortará como si fuera unE_ERROR. | Desde PHP 5.2.0 |
| 8192 | E_DEPRECATED(integer) | Avisos en tiempo de ejecución. Habilítelo para recibir avisos sobre código que no funcionará en futuras versiones. | Desde PHP 5.3.0 |
| 16384 | E_USER_DEPRECATED(integer) | Mensajes de advertencia generados por el usuario. Son como unE_DEPRECATED, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). | Desde PHP 5.3.0 |
| 32767 | E_ALL(integer) | Todos los errores y advertencias soportados, excepto del nivelE_STRICTantes de PHP 5.4.0. | 32767 en PHP 5.4.x, 30719 en PHP 5.3.x, 6143 en PHP 5.2.x, 2047 anteriormente |
Los valores de arriba (numéricos o simbólicos) se usan para construir una máscara de bits que especifica qué errores notificar. Se pueden usar losoperadores a nivel de bitpara combinar estos valores o para enmascarar ciertos tipos de errores. Observe que sólo serán interpretados '|', '~', '!', '^' y '&' dentro dephp.ini.
Abajo podemos ver un ejemplo del uso de las capacidades del manejo de errores de PHP. Definimos una función de gestión de errores que registra la información en un archivo (usado un foramto XML), y envía un e-mail a los desarrolladores en caso de que suceda un error crítico en la lógica.
Ejemplo #1 Usar el manejo de errores en un script
<?php
// haremos nuestro propio manejo de errores
error_reporting(0);
// función de gestión de errores definida por el usuario
functiongestorErrores($númerr,$menserr,$nombrearchivo,$númlínea,$vars)
{
// marca de tiempo para la entrada del error
$fh=date("Y-m-d H:i:s (T)");
// definir una matriz asociativa de cadena de error
// en realidad las únicas entradas que deberíamos
// considerar son E_WARNING, E_NOTICE, E_USER_ERROR,
// E_USER_WARNING y E_USER_NOTICE
$tipoerror= array (
E_ERROR=>'Error',
E_WARNING=>'Warning',
E_PARSE=>'Parsing Error',
E_NOTICE=>'Notice',
E_CORE_ERROR=>'Core Error',
E_CORE_WARNING=>'Core Warning',
E_COMPILE_ERROR=>'Compile Error',
E_COMPILE_WARNING=>'Compile Warning',
E_USER_ERROR=>'User Error',
E_USER_WARNING=>'User Warning',
E_USER_NOTICE=>'User Notice',
E_STRICT=>'Runtime Notice',
E_RECOVERABLE_ERROR=>'Catchable Fatal Error'
);
// conjunto de errores por el cuál se guardará un seguimiento de una variable
$errores_usuario= array(E_USER_ERROR,E_USER_WARNING,E_USER_NOTICE);
$err="<errorentry>\n";
$err.="\t<datetime>".$fh."</datetime>\n";
$err.="\t<errornum>".$númerr."</errornum>\n";
$err.="\t<errortype>".$tipoerror[$númerr] ."</errortype>\n";
$err.="\t<errormsg>".$menserr."</errormsg>\n";
$err.="\t<scriptname>".$nombrearchivo."</scriptname>\n";
$err.="\t<scriptlinenum>".$númlínea."</scriptlinenum>\n";
if (in_array($númerr,$errores_usuario)) {
$err.="\t<vartrace>".wddx_serialize_value($vars,"Variables") ."</vartrace>\n";
}
$err.="</errorentry>\n\n";
// para probar
// echo $err;
// guardar al registro de errores, y enviarme un e-mail si hay un error crítico de usuario
error_log($err,3,"/usr/local/php4/error.log");
if ($númerr==E_USER_ERROR) {
mail("phpdev@example.com","Error Crítico de Usuario",$err);
}
}
functiondistancia($vect1,$vect2)
{
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error("Parámetros incorrectos, se esperaba una matriz",E_USER_ERROR);
returnNULL;
}
if (count($vect1) !=count($vect2)) {
trigger_error("Los vectores necesitan ser del mismo tamaño",E_USER_ERROR);
returnNULL;
}
for ($i=0;$i<count($vect1);$i++) {
$c1=$vect1[$i];$c2=$vect2[$i];
$d=0.0;
if (!is_numeric($c1)) {
trigger_error("La coordenada$idel vector 1 no es un número, se usará cero",
E_USER_WARNING);
$c1=0.0;
}
if (!is_numeric($c2)) {
trigger_error("La coordenada$idel vector 2 no es un número, se usará cero",
E_USER_WARNING);
$c2=0.0;
}
$d+=$c2*$c2-$c1*$c1;
}
returnsqrt($d);
}
$gestor_error_antiguo=set_error_handler("gestorErrores");
// constante no definida, genera una advertencia
$t=NO_ESTOY_DEFINIDA;
// definir algunos "vectores"
$a= array(2,3,"foo");
$b= array(5.5,4.3, -1.6);
$c= array(1, -3);
// generar un error de usuario
$t1=distancia($c,$b) ."\n";
// generar otro error de usuario
$t2=distancia($b,"no soy una matriz") ."\n";
// generar una advertencia
$t3=distancia($a,$b) ."\n";
?>Véase tambiénsyslog().
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
debug_backtrace—Genera un rastreo
$options= DEBUG_BACKTRACE_PROVIDE_OBJECT,int$limit= 0):arraydebug_backtrace()genera un rastreo de PHP.
optionsDesde 5.3.6, este parámetro es una mascara de bits para las siguientes opciones:
| DEBUG_BACKTRACE_PROVIDE_OBJECT | Completar el índice "object" o no. |
| DEBUG_BACKTRACE_IGNORE_ARGS | Omitir el índice "args" y por lo tanto todos los argumentos de las funciones/métodos para ahorrar memoria o no. |
trueofalse, que es lo mismo que establecer y desestablecer la opciónDEBUG_BACKTRACE_PROVIDE_OBJECT.limitDesde 5.4.0, este parámetro puede ser usado para limitar el número de stack frames que se muestran. Por defecto (limit=0) imprime todos los stack frames.
Devuelve un array dearrayasociativos. Los posibles elementos devueltos son los siguientes:
| Nombre | Tipo | Descripción |
|---|---|---|
| function | string | El nombre de la función actual. Véase también__FUNCTION__. |
| line | integer | El número de línea actual. Véase también__LINE__. |
| file | string | El nombre de archivo actual. Véase también__FILE__. |
| class | string | El nombre de laclaseactual. Véase también__CLASS__ |
| object | object | Elobjetoactual. |
| type | string | El tipo de llamada actual. Si es una llamada a un método devuelve "->". Si es una llamada a un método estático devuelve "::". Si es una llamada a una función no se devuelve nada. |
| args | array | Dentro de una función se lista los argumentos de la función. Dentro de un archvo incluido se lista el nombre (o nombres) del archivo incluido. |
| Versión | Descripción |
|---|---|
| 5.4.0 | Añadido el parámetro opcionallimit. |
| 5.3.6 | Se cambió el parámetroprovide_objectaoptionsy se añadió la opción adicionalDEBUG_BACKTRACE_IGNORE_ARGS. |
| 5.2.5 | Se añadió el parámetro opcionalprovide_object. |
| 5.1.1 | Se añadió elobjectactual como posible elemento devuelto. |
Ejemplo #1 Ejemplo dedebug_backtrace()
<?php
// nombre de archivo: /tmp/a.php
functionuna_prueba($str)
{
echo"\nHola:$str";
var_dump(debug_backtrace());
}
una_prueba('amigo');
?>
<?php
// nombre de archivo: /tmp/b.php
include_once'/tmp/a.php';
?>El resultado es similar al siguiente cuando se ejecuta/tmp/b.php:
Hola: amigo
array(2) {
[0]=>
array(4) {
["file"] => string(10) "/tmp/a.php"
["line"] => int(10)
["function"] => string(10) "una_prueba"
["args"]=>
array(1) {
[0] => &string(5) "amigo"
}
}
[1]=>
array(4) {
["file"] => string(10) "/tmp/b.php"
["line"] => int(2)
["args"] =>
array(1) {
[0] => string(10) "/tmp/a.php"
}
["function"] => string(12) "include_once"
}
}
(PHP 5, PHP 7, PHP 8)
debug_print_backtrace—Muestra un rastreo
$options= 0,int$limit= 0):voiddebug_print_backtrace()muestra un rastreo PHP. muestra las llamadas a función, archivos incluídos y el material evaluado medianteeval().
optionsDesde 5.3.6, este parámetro es una máscara de bits para las siguientes opciones:
| DEBUG_BACKTRACE_IGNORE_ARGS | Omitir el índice "args" y por lo tanto todos los argumentos de las funciones/métodos para ahorrar memoria o no. |
limitDesde 5.4.0, este parámetro puede ser usado para limitar el número de stack frames que se muestran. Por defecto (limit=0) imprime todos los stack frames.
No devuelve ningún valor.
| Versión | Descripción |
|---|---|
| 5.4.0 | Añadido el parámetro opcionallimit. |
| 5.3.6 | Añadido el parámetro opcionaloptions. |
Ejemplo #1 Ejemplo dedebug_print_backtrace()
<?php
// archivo include.php
functiona() {
b();
}
functionb() {
c();
}
functionc(){
debug_print_backtrace();
}
a();
?><?php
// archivo prueba.php
// este es el archivo que debe ejecutar
include'include.php';
?>El resultado del ejemplo sería algo similar a:
#0 c() called at [/tmp/include.php:10] #1 b() called at [/tmp/include.php:6] #2 a() called at [/tmp/include.php:17] #3 include(/tmp/include.php) called at [/tmp/prueba.php:3]
(PHP 7, PHP 8)
error_clear_last—Limpiar el error más reciente
Limpia los errores más recientes, no pudiéndose recuperarlos así conerror_get_last().
Ejemplo #1 Un ejemplo deerror_clear_last()
<?php
var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());
@$a=$b;
var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());
?>El resultado del ejemplo sería algo similar a:
NULL
NULL
array(4) {
["type"]=>
int(8)
["message"]=>
string(21) "Undefined variable: b"
["file"]=>
string(9) "%s"
["line"]=>
int(6)
}
NULL
(PHP 5 >= 5.2.0, PHP 7, PHP 8)
error_get_last—Obtener el último error que ocurrió
Obtiene información sobre el último error que ocurrió.
Devuelve una matriz asociativa describiendo el último error con las claves "type" (tipo), "message" (mensaje), "file" (archivo) y "line" (línea). Si el error ha sido causado por una función interna de PHP, el "message" (mensaje) comienza con su nombre. Devuelvenullsi no ha habido aún un error.
Ejemplo #1 Un ejemplo deerror_get_last()
<?php
echo$a;
print_r(error_get_last());
?>El resultado del ejemplo sería algo similar a:
Array
(
[type] => 8
[message] => Undefined variable: a
[file] => C:\WWW\index.php
[line] => 2
)
display_errorshtml_errorsxmlrpc_errors(PHP 4, PHP 5, PHP 7, PHP 8)
error_log—Enviar un mensaje de error a las rutinas de manejo de errores definidas
$message,$message_type= 0,$destination= ?,$extra_headers= ?Envía un mensaje de error al registro de errores del servidor web o a un fichero.
messageEl mensaje de error que debería ser registrado.
message_typeIndica dónde debería ir el error. Los tipos de mensaje posibles son:
| 0 | messagees enviado al registro del sistema de PHP, usando el mecanismo de registro del Sistema Operativo o un fichero, dependiendo de qué directiva de configuración esté establecida enerror_log. Esta opción es la predeterminada. |
| 1 | messagees enviado por email a la dirección del parámetrodestination. Este es el único tipo de mensaje donde se usa el cuarto parámetroextra_headers. |
| 2 | Ya no es una opción. |
| 3 | messagees añadido al final del ficherodestination. No se añade automáticamente una nueva línea al final del stringmessage. |
| 4 | messagees enviado directamente al gestor de registro de la SAPI. |
destinationEl destino. Su significado depende del parámetromessage_typetal como se describió arriba.
extra_headersLas cabeceras extra. Se usa cuando el parámetromessage_typeestá establecido a1. Este tipo de mensaje usa la misma función interna quemail().
Devuelvetrueen caso de éxito ofalseen caso de error.
error_log()no es seguro a nivel binario.messageserá truncado por un carácter null.
messageno debería contener un carácter null. Observe quemessagepodría enviarse a un fichero, correo, syslog, etc. Use la función de conversión/escape apropiada,base64_encode(),rawurlencode()oaddslashes(), antes de llamar aerror_log().
Ejemplo #1 Ejemplos deerror_log()
<?php
// Enviar una notificación al registro del servidor si no podemos
// conectarnos a la base de datos.
if (!Ora_Logon($username,$password)) {
error_log("¡La base de datos de Oracle no está disponible!",0);
}
// Notificar al administrador mediante un email si agotamos FOO
if (!($foo=allocate_new_foo())) {
error_log("Problema serio, nos hemos quedado sin FOOs!",1,
"operator@example.com");
}
// otra manera de llamar a error_log():
error_log("¡Lo echaste a perder!",3,"/var/tmp/my-errors.log");
?>| Versión | Descripción |
|---|---|
| 5.2.7 | El valor posible de 4 se añadió amessage_type. |
(PHP 4, PHP 5, PHP 7, PHP 8)
error_reporting—Establece cuáles errores de PHP son notificados
$level= ?):intLa funciónerror_reporting()establece la directivaerror_reportingen tiempo de ejecución. PHP tiene varios niveles de errores para notificar, al utilizar ésta función se define el nivel de duración (tiempo de ejecución) de sus scripts. Si el parámetro opcionallevelno se define, la funciónerror_reporting()sólo devolverá el nivel actual de notificación de error.
levelEl nuevo nivel deerror_reporting. Este nivel toma una máscara de bit o constantes nominadas. Al utilizar constantes nominadas se recomienda encarecidamente asegurar la compatibilidad para versiones futuras. Según se añaden niveles de error, el rango de los enteros incrementa, por lo que los niveles antiguos de errores basados en enteros no siempre se comportarán como se esperaba.
Las constantes de niveles de error disponibles, y los significados actuales de esos niveles de error están descritos enconstantes predefinidas.
Devuelve el nivel antiguo deerror_reportingo el nivel actual si el parámetrolevelno se proporciona.
| Versión | Descripción |
|---|---|
| 5.4.0 | AhoraE_STRICTes parte deE_ALL. |
| 5.3.0 | Se introdujoE_DEPRECATEDyE_USER_DEPRECATED. |
| 5.2.0 | Se introdujoE_RECOVERABLE_ERROR. |
Ejemplo #1 Ejemplos deerror_reporting()
<?php
// Desactivar toda notificación de error
error_reporting(0);
// Notificar solamente errores de ejecución
error_reporting(E_ERROR|E_WARNING|E_PARSE);
// Notificar E_NOTICE también puede ser bueno (para informar de variables
// no inicializadas o capturar errores en nombres de variables ...)
error_reporting(E_ERROR|E_WARNING|E_PARSE|E_NOTICE);
// Notificar todos los errores excepto E_NOTICE
error_reporting(E_ALL^E_NOTICE);
// Notificar todos los errores de PHP (ver el registro de cambios)
error_reporting(E_ALL);
// Notificar todos los errores de PHP
error_reporting(-1);
// Lo mismo que error_reporting(E_ALL);
ini_set('error_reporting',E_ALL);
?>La mayoría de erroresE_STRICTson evaluados en tiempo de compilación por lo que tales errores no se notifican en el fichero dondeerror_reportingse mejora al incluir los errores deE_STRICT(y viceversa).
Al pasar el valor-1se mostrarán todos los errores posibles, incluso cuando se añadan nuevos niveles y constantes en futuras versiones de PHP. La constanteE_ALLtambién se comporta de esta forma en PHP 5.4.
(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
restore_error_handler—Recupera la función de gestión de errores previa
Usada después de modificar la función de gestión de errores usandoset_error_handler(), para revertir al gestor de errores previo (el cual puede ser el incorporado o una función definida por el usuario).
Esta función siempre devuelvetrue.
Ejemplo #1 Ejemplo derestore_error_handler()
Decidir siunserialize()causó un error, entonces recuperar el gestor de errores original.
<?php
functiongestor_unserialize($errno,$errstr)
{
echo"Valor seriado inválido.\n";
}
$seriado='foo';
set_error_handler('gestor_unserialize');
$original=unserialize($seriado);
restore_error_handler();
?>El resultado del ejemplo sería:
Valor seriado inválido.
(PHP 5, PHP 7, PHP 8)
restore_exception_handler—Restaura la función de gestión de excepciones previamente definida
Usada después de cambiar la función de gestión de excepciones al utilizarset_exception_handler(), para volver al gestor de excepciones anterior (el cuál puede ser la función interna o una definida por el usuario).
Esta función siempre devuelvetrue.
Ejemplo #1 Ejemplo derestore_exception_handler()
<?php
functiongestor_excepciones_1(Exception $e)
{
echo'['.__FUNCTION__.'] '.$e->getMessage();
}
functiongestor_excepciones_2(Exception $e)
{
echo'['.__FUNCTION__.'] '.$e->getMessage();
}
set_exception_handler('gestor_excepciones_1');
set_exception_handler('gestor_excepciones_2');
restore_exception_handler();
throw newException('Esto dispara el primer gestor de excepciones...');
?>El resultado del ejemplo sería:
[gestor_excepciones_1] Esto dispara el primer gestor de excepciones...
(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
set_error_handler—Establecer una función de gestión de errores definida por el usuario
Establece una función de usuario (error_handler) para manejar los errores de un script.
Esta función se puede usar para definir su propia forma de manejar los errores en tiempo de ejecución, por ejemplo en aplicaciones en las que se necesita hacer una limpieza de datos/archivos cuando ocurre un error crítico, o cuando se necesita provocar un error bajo ciertas condiciones (usandotrigger_error()).
Es importante recordar que el gestor de errores estándar de PHP es completamente evitado por los tipos de errores especificados porerror_typesa menos que la función de llamada de retorno devuelvafalse. La configuración deerror_reporting()no tendrá efecto y su gestor de errores será llamado de todas formas - aunque aún es capaz de leer el valor actual deerror_reportingy actuar de manera apropiada. En particular, observe que este valor será 0 si a la sentencia que causó el error se le añadió al principio eloperador de control de errores @.
También observe que es su responsabilidad realizar undie()si fuera necesario. Si la función de gestión de errores devuelve, la ejecución del script continuará con la siguiente sentencia después de la que causó el error.
Los siguientes tipos de errores no pueden ser manejados con una función definida por el usuario:E_ERROR,E_PARSE,E_CORE_ERROR,E_CORE_WARNING,E_COMPILE_ERROR,E_COMPILE_WARNING, y la mayoría deE_STRICTocasionados en el archivo desde donde se llamó aset_error_handler().
Si sucede algún error antes de que el script sea ejecutado (p.ej. en la carga de archivos) el gestor de errores personalizado no podrá ser llamado ya que no está registrado en ese momento.
error_handlerUna llamada de retorno con la siguiente signatura. Se podría pasarnullen su lugar para reiniciar este gestor a su estado predeterminado. También se puede proporcionar un nombre de una función, un array que contenga una referencia a un objeto y un nombre de un método.
$errno,$errstr,$errfile= ?,$errline= ?,$errcontext= ?errnoerrno, contiene el nivel del error ocasionado, como un valor de tipo integer.errstrerrstr, contiene el mensaje de error, como cadena.errfileerrfile, que contiene el nombre de archivo que ocasionó el error, como cadena.errlineerrline, que contiene el número de línea donde ocurrió el error, como valor de tipo integer.errcontexterrcontext, el cuál es una matriz que apunta a la tabla de símbolos activa en el punto donde ocurrió el error. En otras palabras,errcontextcontendrá una matriz con cada variable que existe en el ámbito donde el error fue provocado. El gestor de errores de usuario no debe modificar el contexto del error.Si la función devuelvefalsese continúa con el gestor de errores normal.
error_typesSe puede usar para enmascarar la provocación de la funciónerror_handleral igual que la configuraciónerror_reportingini controla los errores que se muestran. Sin esta máscara establecidaerror_handlerserá llamada para cada error sin tener en cuenta la configuración deerror_reporting.
Devuelve una cadena que contiene el gestor de errores definido anteriormente (si lo hay). Si se usa el gestor de errores interno se devuelvenull.nulltambién es devuelto en caso de un error como una llamada de retorno no válida. Si el gestor de errores anterior era un método de una clase, esta función devolverá una matriz indexada con los nombres de las clases y métodos.
| Versión | Descripción |
|---|---|
| 5.5.0 | error_handlerahora aceptanull. |
| 5.2.0 | El gestor de errores debe devolverfalsepara rellenar$php_errormsg. |
Ejemplo #1 Manejo de errores conset_error_handler()ytrigger_error()
El ejemplo de abajo muestra el manejo de excepciones internas mediante la provocación de errores y tratándolos con una función definida por el usuario:
<?php
// función de gestión de errores
functionmiGestorDeErrores($errno,$errstr,$errfile,$errline)
{
if (!(error_reporting() &$errno)) {
// Este código de error no está incluido en error_reporting
return;
}
switch ($errno) {
caseE_USER_ERROR:
echo"<b>Mi ERROR</b> [$errno]$errstr<br />\n";
echo" Error fatal en la línea$errlineen el archivo$errfile";
echo", PHP ".PHP_VERSION." (".PHP_OS.")<br />\n";
echo"Abortando...<br />\n";
exit(1);
break;
caseE_USER_WARNING:
echo"<b>Mi WARNING</b> [$errno]$errstr<br />\n";
break;
caseE_USER_NOTICE:
echo"<b>Mi NOTICE</b> [$errno]$errstr<br />\n";
break;
default:
echo"Tipo de error desconocido: [$errno]$errstr<br />\n";
break;
}
/* No ejecutar el gestor de errores interno de PHP */
returntrue;
}
// función para probar el manejo de errores
functionscale_by_log($vect,$scale)
{
if (!is_numeric($scale) ||$scale<=0) {
trigger_error("log(x) para x <= 0 no está definido, usó: scale =$scale",E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Vector de entrada incorrecto, se esperaba una matriz de valores",E_USER_WARNING);
returnnull;
}
$temp= array();
foreach($vectas$pos=>$valor) {
if (!is_numeric($valor)) {
trigger_error("El valor en la posición$posno es un número, usando 0 (cero)",E_USER_NOTICE);
$valor=0;
}
$temp[$pos] =log($scale) *$valor;
}
return$temp;
}
// establecer el gestro de errores definido por el usuario
$gestor_errores_antiguo=set_error_handler("miGestorDeErrores");
// provocar algunos errores, primero definimos una matriz mixta con un elemento no numérico
echo"vector a\n";
$a= array(2,3,"foo",5.5,43.3,21.11);
print_r($a);
// ahora generamos una segunda matriz
echo"----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b=scale_by_log($a,M_PI);
print_r($b);
// esto es un problema, pasamos una cadena en vez de una matriz
echo"----\nvector c - a warning\n";
/* Vector de entrada incorrecto, se esperaba una matriz de valores */
$c=scale_by_log("no array",2.3);
var_dump($c);// NULL
// esto es un error crítico, log de cero o de un número negativo es indefinido
echo"----\nvector d - fatal error\n";
/* log(x) para x <= 0 no está definido, usó: scale = $scale */
$d=scale_by_log($a, -2.5);
var_dump($d);// Nunca se alcanza
?>El resultado del ejemplo sería algo similar a:
vector a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>Mi NOTICE</b> [1024] El valor en la posición 2 no es un número, usando 0 (cero)<br />
Array
(
[0] => 2.2894597716988
[1] => 3.4341896575482
[2] => 0
[3] => 6.2960143721717
[4] => 49.566804057279
[5] => 24.165247890281
)
----
vector c - a warning
<b>Mi WARNING</b> [512] Vector de entrada incorrecto, se esperaba una matriz de valores<br />
NULL
----
vector d - fatal error
<b>Mi ERROR</b> [256] log(x) para x <= 0 no está definido, usó: scale = -2.5<br />
Error fatal en la línea 35 en el archivo trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Abortando...<br />
(PHP 5, PHP 7, PHP 8)
set_exception_handler—Establece una función de gestión de excepciones definida por el usuario
Establece el manejador de excepciones predeterminado si una excepción no es capturada dentro de un bloque try/catch. La ejecución se detendrá después de la llamada aexception_handler.
exception_handlerNombre de la función a llamar cuando ocurra una excepción no capturada. Es necesario que esta función de gestión acepte un parámetro, que será el objeto de excepción que fue lanzado. Esta es la firma del manejador:
Desde PHP 7, la mayoría de los errores se notifican lanzando excepcionesError, las cuales serán también capturadas por el manejador.ErroryExceptionimplementan la interfazThrowable. Esta es la signatura del manejador desde PHP 7:
Se podría pasarnullen su lugar para reiniciar este manejador a su estado predeterminado.
Observe que al proporcionar unaExceptionexplícita como tipo implicado al parámetroexen una retrollamada causará problemas con la jerarquía de excepciones cambiada en PHP 7.
Devuelve el nombre del manejador de excepciones definido anteriormente, onullen caso de error. Si no se definió un manejador anterior también devolveránull.
| Versión | Descripción |
|---|---|
| 7.0.0 | Cambiado el tipo de parámetro pasado aexception_handlerdeExceptionaThrowable |
| 5.5.0 | Anteriormente, si se pasabanull, esta función devolvíatrue. Devuelve el manejador anterior desde PHP 5.5.0. |
Ejemplo #1 Ejemplo deset_exception_handler()
<?php
functionmanejador_excepciones($excepción) {
echo"Excepción no capturada: ",$excepción->getMessage(),"\n";
}
set_exception_handler('manejador_excepciones');
throw newException('Excepción No Capturada');
echo"No Ejecutado\n";
?>(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
trigger_error—Generar un mensaje de error/advertencia/aviso de nivel de usuario
$error_msg,int$error_type= E_USER_NOTICE):boolSe usa para provocar una condición de error de usuario, se puede utilizar junto con el gestor de errores interno o con una función definida por el usuario que ha sido establecida como el nuevo gestor de errores (set_error_handler()).
Esta función es útil cuando se necesita generar una respuesta en particular a una excepción en tiempo de ejecución.
error_msgEl mensaje de error designado para este error. Está limitado a 1024 bytes de longitud. Cualquier carácter más allá de los 1024 será truncado.
error_typeEl tipo de error designado para este error. Sólo funciona con la familia de constantes E_USER, y por defecto esE_USER_NOTICE.
Esta función devuelvefalsesi se especifica unerror_typeerróneo, si notrue.
Ejemplo #1 Ejemplo detrigger_error()
Véaseset_error_handler()para un ejemplo más extenso.
<?php
if ($divisor==0) {
trigger_error("No se puede dividir por cero",E_USER_ERROR);
}
?>Las entidades HTML enerror_msgno son escapadas. Usehtmlentities()en el mensaje si el error se va a mostrar en un navegador.
Esta función es un alias de:trigger_error().
This extension allows the loading of shared libraries (.DLLor.so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third “intermediate” language. The public API is implemented as a single classFFIwith several static methods (some of them may be called dynamically), and overloaded object methods, which perform the actual interaction with C data.
FFI is dangerous, since it allows to interface with the system on a very low level. The FFI extension should only be used by developers having a working knowledge of C and the used C APIs. To minimize the risk, the FFI API usage may be restricted with theffi.enablephp.inidirective.
Nota:
The FFI extension does not render the classic PHP extension API obsolete; it is merely provided for ad-hoc interfacing with C functions and data structures.
Currently, accessing FFI data structures is significantly (about 2 times) slower than accessing native PHP arrays and objects. Therefore, it makes no sense to use the FFI extension for speed; however, it may make sense to use it to reduce memory consumption.
To enable the FFI extension, PHP has to be configured with--with-ffi.
Windows users have to includephp_ffi.dllintophp.inito enable the FFI extension.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| ffi.enable | "preload" | PHP_INI_SYSTEM | |
| ffi.preload | "" | PHP_INI_SYSTEM |
He aquí una breve explicación de las directivas de configuración.
ffi.enablestringAllows enabling ("true") or disabling ("false") FFI API usage, or restricting it only to the CLI SAPI and preloaded files ("preload").
The FFI API restrictions only affect theFFIclass, but not overloaded functions ofFFI\CDataobjects. This means that it is possible to create someFFI\CDataobjects in preloaded files, and then to use these directly in PHP scripts.
ffi.preloadstringAllows preloading of FFI bindings during startup, which is not possible withFFI::load()ifopcache.preload_useris set. This directive accepts aDIRECTORY_SEPARATORdelimited list of filenames. The preloaded bindings can be accessed by callingFFI::scope().
Esta extensión no tiene ningún tipo de recurso definido.
Esta extensión no tiene ninguna constante definida.
Before diving into the details of the FFI API, lets take a look at a few examples demonstrating the simplicity of the FFI API usage for regular tasks.
Nota:
Some of these examples requirelibc.so.6and as such will not work on systems where it is not available.
Ejemplo #1 Calling a function from shared library
<?php
// create FFI object, loading libc and exporting function printf()
$ffi=FFI::cdef(
"int printf(const char *format, ...);",// this is a regular C declaration
"libc.so.6");
// call C's printf()
$ffi->printf("Hello %s!\n","world");
?>El resultado del ejemplo sería:
Hello world!
Nota:
Note that some C functions need specific calling conventions, e.g.
__fastcall,__stdcallor,__vectorcall.
Ejemplo #2 Calling a function, returning a structure through an argument
<?php
// create gettimeofday() binding
$ffi=FFI::cdef("
typedef unsigned int time_t;
typedef unsigned int suseconds_t;
struct timeval {
time_t tv_sec;
suseconds_t tv_usec;
};
struct timezone {
int tz_minuteswest;
int tz_dsttime;
};
int gettimeofday(struct timeval *tv, struct timezone *tz);
","libc.so.6");
// create C data structures
$tv=$ffi->new("struct timeval");
$tz=$ffi->new("struct timezone");
// call C's gettimeofday()
var_dump($ffi->gettimeofday(FFI::addr($tv),FFI::addr($tz)));
// access field of C data structure
var_dump($tv->tv_sec);
// print the whole C data structure
var_dump($tz);
?>El resultado del ejemplo sería algo similar a:
int(0)
int(1555946835)
object(FFI\CData:struct timezone)#3 (2) {
["tz_minuteswest"]=>
int(0)
["tz_dsttime"]=>
int(0)
}
Ejemplo #3 Accessing existing C variables
<?php
// create FFI object, loading libc and exporting errno variable
$ffi=FFI::cdef(
"int errno;",// this is a regular C declaration
"libc.so.6");
// print C's errno
var_dump($ffi->errno);
?>El resultado del ejemplo sería:
int(0)
Ejemplo #4 Creating and Modifying C variables
<?php
// create a new C int variable
$x=FFI::new("int");
var_dump($x->cdata);
// simple assignment
$x->cdata=5;
var_dump($x->cdata);
// compound assignment
$x->cdata+=2;
var_dump($x->cdata);
?>El resultado del ejemplo sería:
int(0) int(5) int(7)
Ejemplo #5 Working with C arrays
<?php
// create C data structure
$a=FFI::new("long[1024]");
// work with it like with a regular PHP array
for ($i=0;$i<count($a);$i++) {
$a[$i] =$i;
}
var_dump($a[25]);
$sum=0;
foreach ($aas$n) {
$sum+=$n;
}
var_dump($sum);
var_dump(count($a));
var_dump(FFI::sizeof($a));
?>El resultado del ejemplo sería:
int(25) int(523776) int(1024) int(8192)
Ejemplo #6 Working with C enums
<?php
$a=FFI::cdef('typedef enum _zend_ffi_symbol_kind {
ZEND_FFI_SYM_TYPE,
ZEND_FFI_SYM_CONST = 2,
ZEND_FFI_SYM_VAR,
ZEND_FFI_SYM_FUNC
} zend_ffi_symbol_kind;
');
var_dump($a->ZEND_FFI_SYM_TYPE);
var_dump($a->ZEND_FFI_SYM_CONST);
var_dump($a->ZEND_FFI_SYM_VAR);
?>El resultado del ejemplo sería:
int(0) int(2) int(3)
It is possible to assign a PHP closure to a native variable of function pointer type or to pass it as a function argument:
<?php
$zend=FFI::cdef("
typedef int (*zend_write_func_t)(const char *str, size_t str_length);
extern zend_write_func_t zend_write;
");
echo"Hello World 1!\n";
$orig_zend_write= clone$zend->zend_write;
$zend->zend_write= function($str,$len) {
global$orig_zend_write;
$orig_zend_write("{\n\t",3);
$ret=$orig_zend_write($str,$len);
$orig_zend_write("}\n",2);
return$ret;
};
echo"Hello World 2!\n";
$zend->zend_write=$orig_zend_write;
echo"Hello World 3!\n";
?>El resultado del ejemplo sería:
Hello World 1!
{
Hello World 2!
}
Hello World 3!
It is therefore recommended to minimize the usage of PHP callbacks.
php.ini
ffi.enable=preload opcache.preload=preload.php
preload.php
<?php
FFI::load(__DIR__."/dummy.h");
opcache_compile_file(__DIR__."/dummy.php");
?>dummy.h
#define FFI_SCOPE "DUMMY" #define FFI_LIB "libc.so.6" int printf(const char *format, ...);
dummy.php
<?php
final classDummy{
private static$ffi=null;
function__construct() {
if (is_null(self::$ffi)) {
self::$ffi=FFI::scope("DUMMY");
}
}
functionprintf($format, ...$args) {
return (int)self::$ffi->printf($format, ...$args);
}
}
?>test.php
<?php
$d= newDummy();
$d->printf("Hello %s!\n","world");
?>(PHP 7 >= 7.4.0, PHP 8)
Objects of this class are created by the factory methodsFFI::cdef(),FFI::load()orFFI::scope(). Defined C variables are made available as properties of the FFI instance, and defined C functions are made available as methods of the FFI instance. Declared C types can be used to create new C data structures usingFFI::new()andFFI::type().
FFI definition parsing and shared library loading may take significant time. It is not useful to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files may be extended with specialFFI_SCOPEdefines (e.g.#define FFI_SCOPE "foo"”"; the default scope is "C") and then loaded byFFI::load()during preloading. This leads to the creation of a persistent binding, that will be available to all the following requests throughFFI::scope(). Refer to thecomplete PHP/FFI/preloading examplefor details.
It is possible to preload more than one C header file into the same scope.
FFI::__BIGGEST_ALIGNMENT__(PHP 7 >= 7.4.0, PHP 8)
FFI::addr—Creates an unmanaged pointer to C data
Creates an unmanaged pointer to the C data represented by the givenFFI\CData. The sourceptrmust survive the resulting pointer. This function is mainly useful to pass arguments to C functions by pointer.
ptrThe handle of the pointer to a C data structure.
Returns the freshly createdFFI\CDataobject.
(PHP 7 >= 7.4.0, PHP 8)
FFI::alignof—Gets the alignment
ptrThe handle of the C data or type.
(PHP 7 >= 7.4.0, PHP 8)
FFI::arrayType—Dynamically constructs a new C array type
Dynamically constructs a new C array type with elements of type defined bytype, and dimensions specified bydimensions. In the following example$t1and$t2are equivalent array types:
<?php
$t1=FFI::type("int[2][3]");
$t2=FFI::arrayType(FFI::type("int"), [2,3]);
?>typeA valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.
dimensionsThe dimensions of the type asarray.
Returns the freshly createdFFI\CTypeobject.
(PHP 7 >= 7.4.0, PHP 8)
FFI::cast—Performs a C type cast
FFI::cast()creates a newFFI\CDataobject, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the sourceptrmust survive the result. The C type may be specified as astringwith any valid C type declaration or asFFI\CTypeobject, created before. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.
typeA valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.
ptrThe handle of the pointer to a C data structure.
Returns the freshly createdFFI\CDataobject.
(PHP 7 >= 7.4.0, PHP 8)
FFI::cdef—Creates a new FFI object
codeA string containing a sequence of declarations in regular C language (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files.
Nota:
C preprocessor directives are not supported, i.e.
#include,#defineand CPP macros do not work.
libThe name of a shared library file, to be loaded and linked with the definitions.
Nota:
If
libis omitted, platforms supportingRTLD_DEFAULTattempt to lookup symbols declared incodein the normal global scope. Other systems will fail to resolve these symbols.
Returns the freshly createdFFIobject.
| Versión | Descripción |
|---|---|
| 8.0.0 | libis nullable now. |
(PHP 7 >= 7.4.0, PHP 8)
FFI::free—Releases an unmanaged data structure
Manually releases a previously created unmanaged data structure.
ptrThe handle of the unmanaged pointer to a C data structure.
No devuelve ningún valor.
(PHP 7 >= 7.4.0, PHP 8)
FFI::isNull—Checks whether a FFI\CData is a null pointer
Checks whether a FFI\CData is a null pointer.
ptrThe handle of the pointer to a C data structure.
Returns whether a FFI\CData is a null pointer.
(PHP 7 >= 7.4.0, PHP 8)
FFI::load—Loads C declarations from a C header file
Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, using specialFFI_LIBdefines in the loaded C header file.
filenameThe name of a C header file.
C preprocessor directives are not supported, i.e.#include,#defineand CPP macros do not work, except for special cases listed below.
The header fileshouldcontain a#definestatement for theFFI_SCOPEvariable, e.g.:#define FFI_SCOPE "MYLIB". Refer to theclass introductionfor details.
The header filemaycontain a#definestatement for theFFI_LIBvariable to specify the library it exposes. If it is a system library only the file name is required, e.g.:#define FFI_LIB "libc.so.6". If it is a custom library, a relative path is required, e.g.:#define FFI_LIB "./mylib.so".
Returns the freshly createdFFIobject, ornullon failure.
(PHP 7 >= 7.4.0, PHP 8)
FFI::memcmp—Compares memory areas
Comparessizebytes from the memory areasptr1andptr2. Bothptr1andptr2can be any native data structures (FFI\CData) or PHPstrings.
ptr1The start of one memory area.
ptr2The start of another memory area.
sizeThe number of bytes to compare.
Returns <0if the contents of the memory area starting atptr1are considered less than the contents of the memory area starting atptr2, >0if the contents of the first memory area are considered greater than the second, and0if they are equal.
(PHP 7 >= 7.4.0, PHP 8)
FFI::memcpy—Copies one memory area to another
Copiessizebytes from the memory areafromto the memory areato.
toThe start of the memory area to copy to.
fromThe start of the memory area to copy from.
sizeThe number of bytes to copy.
No devuelve ningún valor.
(PHP 7 >= 7.4.0, PHP 8)
FFI::memset—Fills a memory area
Fillssizebytes of the memory area pointed to byptrwith the given bytevalue.
ptrThe start of the memory area to fill.
valueThe byte to fill with.
sizeThe number of bytes to fill.
No devuelve ningún valor.
(PHP 7 >= 7.4.0, PHP 8)
FFI::new—Creates a C data structure
Creates a native data structure of the given C type. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.
typetypeis a valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.
ownedWhether to create owned (i.e. managed) or unmanaged data. Managed data lives together with the returnedFFI\CDataobject, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by callingFFI::free(), when no longer needed.
persistentWhether to allocate the C data structure permanently on the system heap (usingmalloc()), or on the PHP request heap (usingemalloc()).
Returns the freshly createdFFI\CDataobject, ornullon failure.
(PHP 7 >= 7.4.0, PHP 8)
FFI::scope—Instantiates an FFI object with C declarations parsed during preloading
Instantiates an FFI object with C declarations parsed during preloading.
TheFFI::scope()method is safe to call multiple times for the same scope. Multiple references to the same scope may be loaded at the same time.
nameThe scope name defined by a specialFFI_SCOPEdefine.
Returns the freshly createdFFIobject.
(PHP 7 >= 7.4.0, PHP 8)
FFI::sizeof—Gets the size of C data or types
ptrThe handle of the C data or type.
The size of the memory area pointed at byptr.
(PHP 7 >= 7.4.0, PHP 8)
FFI::string—Creates a PHP string from a memory area
Creates a PHPstringfromsizebytes of the memory area pointed to byptr.
ptrThe start of the memory area from which to create astring.
sizeThe number of bytes to copy to thestring. Ifsizeis omitted,ptrmust be a zero terminated array of Cchars.
The freshly created PHPstring.
| Versión | Descripción |
|---|---|
| 8.0.0 | sizeis nullable now; previously, its default was0. |
(PHP 7 >= 7.4.0, PHP 8)
FFI::type—Creates an FFI\CType object from a C declaration
This function creates and returns aFFI\CTypeobject for the givenstringcontaining a C type declaration. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.
typeA valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.
Returns the freshly createdFFI\CTypeobject, ornullon failure.
(PHP 7 >= 7.4.0, PHP 8)
FFI::typeof—Gets the FFI\CType of FFI\CData
ptrThe handle of the pointer to a C data structure.
(PHP 7 >= 7.4.0, PHP 8)
FFI\CDataobjects can be used in a number of ways as a regular PHP data:
$x = FFI::new('int'); $x->cdata = 42;$cdata->field$cdata[$offset]$cdata[0]<,<=,==,!=,>=,>).+/-/++/–-operations, e.g.$cdata += 5-operations.$cdata()$cdata2 = clone $cdata;Nota:Notable limitations are thatFFI\CDatainstances do not supportisset(),empty()andunset(), and that wrapped C structs and unions do not implementTraversable.
(PHP 7 >= 7.4.0, PHP 8)
FFI\CType::TYPE_VOIDFFI\CType::TYPE_FLOATFFI\CType::TYPE_DOUBLEFFI\CType::TYPE_LONGDOUBLEFFI\CType::TYPE_UINT8FFI\CType::TYPE_SINT8FFI\CType::TYPE_UINT16FFI\CType::TYPE_SINT16FFI\CType::TYPE_UINT32FFI\CType::TYPE_SINT32FFI\CType::TYPE_UINT64FFI\CType::TYPE_SINT64FFI\CType::TYPE_ENUMFFI\CType::TYPE_BOOLFFI\CType::TYPE_CHARFFI\CType::TYPE_POINTERFFI\CType::TYPE_FUNCFFI\CType::TYPE_ARRAYFFI\CType::TYPE_STRUCTFFI\CType::ATTR_CONSTFFI\CType::ATTR_INCOMPLETE_TAGFFI\CType::ATTR_VARIADICFFI\CType::ATTR_INCOMPLETE_ARRAYFFI\CType::ATTR_VLAFFI\CType::ATTR_UNIONFFI\CType::ATTR_PACKEDFFI\CType::ATTR_MS_STRUCTFFI\CType::ATTR_GCC_STRUCTFFI\CType::ABI_DEFAULTFFI\CType::ABI_CDECLFFI\CType::ABI_FASTCALLFFI\CType::ABI_THISCALLFFI\CType::ABI_STDCALLFFI\CType::ABI_PASCALFFI\CType::ABI_REGISTERFFI\CType::ABI_MSFFI\CType::ABI_SYSVFFI\CType::ABI_VECTORCALL(PHP 8 >= 8.1.0)
FFI\CType::getAlignment—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getArrayElementType—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getArrayLength—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getAttributes—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getEnumKind—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getFuncABI—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getFuncParameterCount—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getFuncParameterType—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
index(PHP 8 >= 8.1.0)
FFI\CType::getFuncReturnType—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getKind—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 7 >= 7.4.0, PHP 8)
FFI\CType::getName—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getPointerType—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getSize—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getStructFieldNames—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 8 >= 8.1.0)
FFI\CType::getStructFieldOffset—Description
$name):intEsta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
name(PHP 8 >= 8.1.0)
FFI\CType::getStructFieldType—Description
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
name(PHP 7 >= 7.4.0, PHP 8)
OPcache mejora el rendimiento de PHP almacenando el código de bytes de un script precompilado en la memoria compartida, eliminando así la necesidad de que PHP cargue y analice los script en cada petición.
Esta extensión está incluída en PHP 5.5.0 y posteriores, y está» disponible en PECLpara las versiones 5.2, 5.3 y 5.4 de PHP.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
El proceso de instalación de OPcache varía dependiendo de la versión de PHP que se esté usando. Consulte la sección de abajo acorde a la versión que se esté empleando.
Nota:
Si fuera necesario utilizar OPcache con» Xdebug, se debe cargar OPcache antes que Xdebug.
OPcache solamente se podrá compilar como una extensión compartida. Si se ha deshabilitado la construcción de extensiones predeterminadas por medio de--disable-all, se debe compilar PHP con la la opción--enable-opcachepara que OPcache esté disponible.
Una vez compilada, se puede usar la directiva de configuraciónzend_extensionpara cargar la extensión OPcache en PHP. Esto se puede realizar por medio dezend_extension=/full/path/to/opcache.soen plataformas diferentes de Windows, y conzend_extension=C:\path\to\php_opcache.dllen Windows.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/ZendOpcache.
Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Se recomiendan generalmente las siguientes opciones para proveer un buen rendimiento:
opcache.memory_consumption=128 opcache.interned_strings_buffer=8 opcache.max_accelerated_files=4000 opcache.revalidate_freq=60 opcache.fast_shutdown=1 opcache.enable_cli=1
Tambien se podría considerar deshabilitaropcache.save_commentsy habilitaropcache.enable_file_override, aunque se deberá probar el código antes de utilizarlas durante producción, ya que se sabe que causan problemas en marcos de trabajo y aplicaciones, particularmente en casos donde se utilizan anotaciones de comentarios en la documentación.
También está disponibleuna lista completa de directivas de configuración admitidas por OPcache.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| opcache.enable | "1" | PHP_INI_ALL | |
| opcache.enable_cli | "0" | PHP_INI_SYSTEM | Entre PHP 7.1.2 y 7.1.6 inclusive, el valor predetermindao era "1" |
| opcache.memory_consumption | "128" | PHP_INI_SYSTEM | |
| opcache.interned_strings_buffer | "8" | PHP_INI_SYSTEM | |
| opcache.max_accelerated_files | "10000" | PHP_INI_SYSTEM | Antes de PHP 7.0.0 el valor predeterminado era "2000" |
| opcache.max_wasted_percentage | "5" | PHP_INI_SYSTEM | |
| opcache.use_cwd | "1" | PHP_INI_SYSTEM | |
| opcache.validate_timestamps | "1" | PHP_INI_ALL | |
| opcache.revalidate_freq | "2" | PHP_INI_ALL | |
| opcache.revalidate_path | "0" | PHP_INI_ALL | |
| opcache.save_comments | "1" | PHP_INI_SYSTEM | |
| opcache.fast_shutdown | "0" | PHP_INI_SYSTEM | Eliminado en PHP 7.2.0. |
| opcache.enable_file_override | "0" | PHP_INI_SYSTEM | |
| opcache.optimization_level | "0x7FFFBFFF" | PHP_INI_SYSTEM | Cambiado desde 0xFFFFFFFF en PHP 5.6.18 |
| opcache.inherited_hack | "1" | PHP_INI_SYSTEM | Eliminado en PHP 7.3.0. |
| opcache.dups_fix | "0" | PHP_INI_ALL | |
| opcache.blacklist_filename | "" | PHP_INI_SYSTEM | |
| opcache.max_file_size | "0" | PHP_INI_SYSTEM | |
| opcache.consistency_checks | "0" | PHP_INI_ALL | |
| opcache.force_restart_timeout | "180" | PHP_INI_SYSTEM | |
| opcache.error_log | "" | PHP_INI_SYSTEM | |
| opcache.log_verbosity_level | "1" | PHP_INI_SYSTEM | |
| opcache.record_warnings | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.preferred_memory_model | "" | PHP_INI_SYSTEM | |
| opcache.protect_memory | "0" | PHP_INI_SYSTEM | |
| opcache.mmap_base | null | PHP_INI_SYSTEM | |
| opcache.restrict_api | "" | PHP_INI_SYSTEM | |
| opcache.file_update_protection | "2" | PHP_INI_ALL | |
| opcache.huge_code_pages | "0" | PHP_INI_SYSTEM | |
| opcache.lockfile_path | "/tmp" | PHP_INI_SYSTEM | |
| opcache.opt_debug_level | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.1.0 |
| opcache.file_cache | NULL | PHP_INI_SYSTEM | |
| opcache.file_cache_only | "0" | PHP_INI_SYSTEM | |
| opcache.file_cache_consistency_checks | "1" | PHP_INI_SYSTEM | |
| opcache.file_cache_fallback | "1" | PHP_INI_SYSTEM | Solo Windows. |
| opcache.validate_permission | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.0.14 |
| opcache.validate_root | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.0.14 |
| opcache.preload | "" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.4.0 |
| opcache.preload_user | "" | PHP_INI_SYSTEM | Disponible a partir de PHP 7.4.0 |
| opcache.cache_id | "" | PHP_INI_SYSTEM | Solo Windows. Disponible a partir de PHP 7.4.0 |
| opcache.jit | "tracing" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_buffer_size | "0" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_debug | "0" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_bisect_limit | "0" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_prof_threshold | "0.005" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_root_traces | "1024" | PHP_INI_SYSTEM | Disponible a partir PHP 8.0.0 |
| opcache.jit_max_side_traces | "128" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_exit_counters | "8192" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_hot_loop | "64" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_hot_func | "127" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_hot_return | "8" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_hot_side_exit | "8" | PHP_INI_SYSTEM | Disponible a partir de PHP 8.0.0 |
| opcache.jit_blacklist_root_trace | "16" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_blacklist_side_trace | "8" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_loop_unrolls | "8" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_recursive_calls | "2" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_recursive_returns | "2" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
| opcache.jit_max_polymorphic_calls | "2" | PHP_INI_ALL | Disponible a partir de PHP 8.0.0 |
He aquí una breve explicación de las directivas de configuración.
opcache.enablebooleanHabilita la caché de opcode. Cuando está deshabilitado, el código no es optimizado o almacenado en caché. El ajusteopcache.enableno puede ser habilitado en tiempo de ejecución enabled at runtime a través deini_set(), solamente puede ser deshabilitado. Intentar habilitarlo en un script gernerará una advertencia.
opcache.enable_clibooleanHabilita la caché de opcode para la versión CLI de PHP.
opcache.memory_consumptionintegerEL tamaño del almacén de memoria compartida utilizado por OPcache, en megabytes.
opcache.interned_strings_bufferintegerLa cantidad de memoria utilizada para almacenar cadenas, en megabytes. Esta directiva de configuración es ignorada en PHP < 5.3.0.
opcache.max_accelerated_filesintegerEl número máximo de claves (y por lo tanto, de scripts) en la tabla de hash de OPcache. El valor que realmente se utilizará será el primer número en el conjunto de los números primos{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987 }que sea mayor o igual al valor configurado. El valor mínimo es 200. El valor máximo es 100000 en PHP < 5.5.6, y 1000000 en versiones posteriores.
opcache.max_wasted_percentageintegerEl porcentaje máximo de memoria desperdiciada que está permitida antes de que un reinicio sea programado.
opcache.use_cwdbooleanSi está habilitada, OPcache añade el directorio de trabajo actual a la clave del script, eliminado así las posibles colisiones entre ficheros con el mismo nombre base. Deshabilitar esta directiva mejora el rendimiento pero podría generar problemas en aplicaciones existentes.
opcache.validate_timestampsbooleanSi está habilitado, OPcache consultará por scripts actualizados cadaopcache.revalidate_freqsegundos. Cuando esta directiva está deshabilitada, se debe reiniciar OPcache de forma manual medianteopcache_reset(),opcache_invalidate()o reiniciando el servidor web para que los cambios en el sistema de ficheros tomen efecto.
opcache.revalidate_freqintegerLa frecuencia de verificación de las marcas temporales de Unix de los scripts por actualizaciones, en segundos.0hará que OPcache consulte por actualizaciones en cada petición.
Esta directiva de configuración es ignorada siopcache.validate_timestampsestá deshabilitada.
opcache.revalidate_pathbooleanSi está deshabilitada, los ficheros cacheados existentes que usen el mismoinclude_pathserán reutilizados. Por lo tanto, si un fichero con el mismo nombre está en algún otro lado del include_path, no será encontrado.
opcache.save_commentsbooleanSi está deshabilitada, todos los comentarios de la documentación serán elliminados de la caché de opcode para reducir el tamaño del código optimizado. Deshabilitar esta directiva de configuración podría generar problemas en aplicaciones y frameworks que dependen del análisis de comentarios para anotaciones, incluyendo Doctrine, Zend Framework 2 y PHPUnit.
opcache.load_commentsbooleanSi está deshabilitada, los comentarios de la documentación no serán cargados de la caché de opcode aun si éstos existen. Esto puede ser usado junto conopcache.save_commentspara cargar sólo los comentarios para las aplicaciones que los requieran.
opcache.fast_shutdownbooleanSi está habilitada, una secuencia de apagado rápida es utilizada que no libera cada bloque asignado sino que depende del gestor de memoria del Zend Engine para rescindir del conjunto de variables de petición completo.
Esta directiva ha sido eliminada en PHP 7.2.0. Se ha integrado una variante de la secuencia de apagado rápido en PHP, y será usada automáticamente si es posible.
opcache.enable_file_overridebooleanCuando está habilitada, la caché de opcode será consultado para determinar si un fichero ya ha sido cacheado cuandofile_exists(),is_file()yis_readable()son llamadas. Esto puede incrementar el rendimiento en aplicaciones que chequean la existencia y legibilidad de los scripts PHP, pero arriesgando devolver datos obsoletos siopcache.validate_timestampsestá deshabilitada.
opcache.optimization_levelintegerUn bitmask que controla cúales permisos de optimización son ejecutados.
opcache.inherited_hackboolEsta directiva de configuración es ignorada.
opcache.dups_fixbooleanEste hack debería estar habilitado para funcionar sólo para evitar errores "Cannot redeclare class".
opcache.blacklist_filenamestringLa ubicación del fichero de blacklist de OPcache. Un fichero blacklist es un texto que contiene los nombres de los ficheros que no deberían ser acelerados, uno por línea. Se permiten comodines, y prefijos también pueden ser provistos. Las líneas que comienzen con un punto y coma son ignoradas como comentarios.
Un fichero blacklist simple luciría así:
; Matches a specific file. /var/www/broken.php ; A prefix that matches all files starting with x. /var/www/x ; A wildcard match. /var/www/*-broken.php
opcache.max_file_sizeintegerEl tamaño de fichero máximo que será almacenado en caché, en bytes. Si es0, todos los ficheros serán almacenados en caché.
opcache.consistency_checksintegerSi es distinto de cero, OPcache verificará el checksum de la caché cada N peticiones, donde N es el valor de esta directiva de configuración. Esto debería sólo estar habilitado durante la depuración ya que puede tener un impacto negativo en el rendimiento.
opcache.force_restart_timeoutintegerLa cantidad de tiempo a esperar el comienzo de un reinicio programado si la caché no está activa, en segundos. Si se acaba el tiempo, entonces OPcache asume que algo anda mal y terminará todos los procesos que bloqueen la caché para permitir un reinicio.
Siopcache.log_verbosity_leveles 2 o más, una advertencia será guardada en el registro de errores si esto ocurre.
opcache.error_logstringEl registro de errores de errores de OPcache. Una cadena vacía es tratada de igual forma questderr, y resultará en registros siendo enviados a errores estándar (que será el registro de errores del servidor Web en la mayoría de los casos).
opcache.log_verbosity_levelintegerEl nivel de verbosidad del registro. Por defecto, sólo los errores fatales (nivel 0) y errores (nivel 1) son registrados. Otros niveles disponibles son advertencias (nivel 2), mensajes de información (nivel 3) y mensajes de depuración (nivel 4).
opcache.record_warningsboolIf enabled, OPcache will record compile-time warnings and replay them on the next include, even if it is served from cache.
opcache.preferred_memory_modelstringEl modelo de memoria principal que utilizará OPcache. Si se deja vacío, OPcache seleccionará el modelo más apropiado, el cual es el comportamiento correcto en prácticamente todos los casos.
Los valores posibles incluyenmmap,shm,posixywin32.
opcache.protect_memorybooleanProtege la memoria compartida de escrituras inesperadas mientras se ejecutan scripts. Esto es útil sólo para depuración interna.
opcache.mmap_basestringLa base usada para los segmentos de memoria compartida en Windows. Todos los procesos PHP deben mapear la memoria compartida con el mismo espacio de direcciones. Utilizando esta directiva se corrigen los errores "Unable to reattach to base address".
opcache.restrict_apistringPermite llamar a funciones de la API de OPcache solamente desde scripts de PHP cuya ruta comience con la cadena especificada. El valor predeterminado de "" significa sin restricciones.
opcache.file_update_protectionstringPreviene de almacenar en caché ficheros que estén menos que este número de segundos. Protege del almacenamiento en caché de ficheros no actualizados completamente. En caso de que todas las actualizaciones de ficheros del sitio sean atómicas, se puede aumentar el rendimiento estableciéndolo a "0".
opcache.huge_code_pagesstringHabilita o inhabilita la copia de código de PHP (segmento de texto) a HUGE PAGES. Esto debería mejorar el rendimiento, aunque requiere una configuración apropiada del SO.
opcache.lockfile_pathstringRuta absoluta usada para almacenar shared lockfiles compartidos (solo para *nix)
opcache.opt_debug_levelstringProduce volcados de opcode para depurar diferentes escenarios de optimización. 0x10000 generará opcodes a medida que el compilador los haya producido antes de ocurra cualquier optimización, mientras que 0x20000 generará códigos optimizados.
opcache.file_cachestringHabilita y establece el segundo nivel de directorio de caché. Debería mejorar el rendimiento cuando la memoria SHM esté llena, cuando se reinicie el servidor o se restablezca la SHM. El valor predeterminado "" inhabilita el almacenamiento en cache basado en ficheros.
opcache.file_cache_onlybooleanHabilita o inhabilita el almacenamiento de opcodes en memoria compartida.
opcache.file_cache_consistency_checksbooleanHabilita o inhabilita la validación del checksum cuando un script sea cargado desde la caché de ficheros.
opcache.file_cache_fallbackbooleanImplica opcache.file_cache_only=1 para ciertos procesos que fallan al volver a vincularse a la memoria conpartida (solo Windows). Es necesaria la caché de ficheros explícitamente.
La inhabilitación de esta opción de configuración puede evitar el inicio de procesos, por lo que está desaconsejado.
opcache.validate_permissionbooleanValida los permisos de ficheros almacenados en caché con el usuario en uso.
opcache.validate_rootbooleanEvita la colisión de nombres en entornos con chroot. Debe estar habilitado en todos los entornos con chroot para evitar el acceso a ficheros fuera de chroot.
opcache.preloadstringEspecifica un script de PHP que va a ser compilado y ejecutado en el arranque del servidor, lo que podría precargar otros ficheros, ya sea conincludeo usando la funciónopcache_compile_file(). Todas las entidades (p. ej. funciones y clases) definidas en estos ficheros estarán disponibles para peticiones listas para usar, hasta que el servidor sea apagado.
opcache.preload_userstringLa precarga de código como «root» no está permitida por razones de seguridad. Esta directiva facilita que la precarga se ejecute como otro usuario.
opcache.cache_idstringOn Windows, all processes running the samePHPSAPIunder the same user account having the same cache ID share a single OPcache instance. The value of the cache ID can be freely chosen.
For IIS, different application pools can have their own OPcache instance by using the environment variableAPP_POOL_IDasopcache.cache_id.
opcache.jitstring|intFor typical usage, this option accepts one of four string values:
disable: Completely disabled, cannot be enabled at runtime.off: Disabled, but can be enabled at runtime.tracing/on: Use tracing JIT. Enabled by default and recommended for most users.function: Use function JIT.For advanced usage, this option accepts a 4-digit integerCRTO, where the digits mean:
C(CPU-specific optimization flags)0: Disable CPU-specific optimization.1: Enable use of AVX, if the CPU supports it.R(register allocation)0: Don't perform register allocation.1: Perform block-local register allocation.2: Perform global register allocation.T(trigger)0: Compile all functions on script load.1: Compile functions on first execution.2: Profile functions on first request and compile the hottest functions afterwards.3: Profile on the fly and compile hot functions.4: Currently unused.5: Use tracing JIT. Profile on the fly and compile traces for hot code segments.O(optimization level)0: No JIT.1: Minimal JIT (call standard VM handlers).2: Inline VM handlers.3: Use type inference.4: Use call graph.5: Optimize whole script."tracing"mode corresponds toCRTO = 1254, the"function"mode corresponds toCRTO = 1205.opcache.jit_buffer_sizeintThe amount of shared memory to reserve for compiled JIT code. A zero value disables the JIT.
Cuando se usa uninteger, el valor del mismo es medido en bytes. También se puede usar la notación reducida, tal como se describe enesta FAQ.opcache.jit_debugintA bit mask specifying which JIT debug output to enable. For possible values, please consultzend_jit.h.
opcache.jit_bisect_limitintDebugging option that disables JIT compilation after compiling a certain number of functions. This may be helpful to bisect the source of a JIT miscompilation. Note: this option only works when JIT trigger is set to 0 (compile on script load) or 1 (compile on first execution), e.g.,opcache.jit=1215. See more inopcache.jitoption.
opcache.jit_prof_thresholdfloatWhen using the "profile on first request" trigger mode, this threshold determines whether a function is considered hot. The number of calls to the function divided by the number of calls to all functions must be above the threshold. For example, a threshold of 0.005 means that functions that made up more than 0.5% of all calls will be JIT compiled.
opcache.jit_max_root_tracesintMaximum number of root traces. The root trace is an execution flow taking one path through the code firstly, which is a unit of JIT compilation. JIT will not compile new code if it reaches this limit.
opcache.jit_max_side_tracesintMaximum number of side traces a root trace may have. The side trace is another execution flow that does not follow the path of compiled root trace. Side traces belonging to the same root trace will not be compiled if it reaches this limit.
opcache.jit_max_exit_countersintMaximum number of side trace exit counters. This limits the total number of side traces there may be, across all root traces.
opcache.jit_hot_loopintAfter how many iterations a loop is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any loops.
opcache.jit_hot_funcintAfter how many calls a function is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any functions.
opcache.jit_hot_returnintAfter how many returns a return is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any returns.
opcache.jit_hot_side_exitintAfter how many exits a side exit is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any side exits.
opcache.jit_blacklist_root_traceintMaximum number of times the compilation of a root trace is attempted before it is blacklisted.
opcache.jit_blacklist_side_traceintMaximum number of times the compilation of a side trace is attempted before it is blacklisted.
opcache.jit_max_loop_unrollsintMaximum number of attempts to unroll a loop in a side trace, trying to reach the root trace and close the outer loop.
opcache.jit_max_recursive_callsintMaximum number of unrolled recursive call loops.
opcache.jit_max_recursive_returnsintMaximum number of unrolled recursive return loops.
opcache.jit_max_polymorphic_callsintMaximum number of attempts to inline polymorphic (dynamic or method) calls. Calls above this limit are treated as megamorphic and are not inlined.
Esta extensión no tiene ningún tipo de recurso definido.
As of PHP 7.4.0, PHP can be configured to preload scripts into the opcache when the engine starts. Any symbols (functions, classes, etc.) in those files will then become globally available for all requests without needing to be explicitly included. That trades convenience and performance (because the code is always available) for baseline memory usage. It also requires restarting the PHP process to clear pre-loaded scripts, meaning this feature is only practical to use in production, not in a development environment.
Note that the optimal tradeoff between performance and memory may vary with the application. "Preload everything" may be the easiest strategy, but not necessarily the best strategy. Additionally, preloading is only useful when there is a persistent process from one request to another. That means while it can work in a CLI script if the opcache is enabled, it's generally pointless. The exception is when using preloading onFFI libraries.
Nota:
Preloading is not supported on Windows.
Configuring preloading involves two steps, and requires that the opcache be enabled. First, set theopcache.preloadvalue inphp.ini:
opcache.preload=preload.php
preload.phpis an arbitrary file that will run once at server startup (PHP-FPM, mod_php, etc.) and load code into persistent memory. If PHP will be run as root (not recommended), theopcache.preload_uservalue can specify an alternate system user to run the preloading. Running preloading as root is not allowed.
In thepreload.phpscript, any file referenced byinclude,include_once,require,require_once, oropcache_compile_file()will be parsed into persistent memory. In the following example, all.phpfiles in thesrcdirectory will be preloaded, unless they are aTestfile.
<?php
$directory= newRecursiveDirectoryIterator(__DIR__.'/src');
$fullTree= newRecursiveIteratorIterator($directory);
$phpFiles= newRegexIterator($fullTree,'/.+((?<!Test)+\.php$)/i',RecursiveRegexIterator::GET_MATCH);
foreach ($phpFilesas$key=>$file) {
require_once($file[0]);
}
?>Bothincludeandopcache_compile_file()will work, but have different implications for how code gets handled.
Aandb.phpdefines classBthat extendsA, thenopcache_compile_file()can load those two files in any order. When usinginclude, however,a.phpmustbe included first.(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)
opcache_compile_file—Compiles and caches a PHP script without executing it
$filename):boolThis function compiles a PHP script and adds it to the opcode cache without executing it. This can be used to prime the cache after a Web server restart by pre-caching files that will be included in later requests.
filenameThe path to the PHP script to be compiled.
Returnstrueiffilenamewas compiled successfully ofalseen caso de error.
Iffilenamecannot be loaded or compiled, an error of levelE_WARNINGis generated. You may use@to suppress this warning.
(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)
opcache_get_configuration—Get configuration information about the cache
This function returns configuration information about the cache instance
Returns an array of information, including ini, blacklist and version
Ifopcache.restrict_apiis in use and the current path is in violation of the rule, an E_WARNING will be raised; no status information will be returned.
(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)
opcache_get_status—Get status information about the cache
$include_scripts=true):array|falseThis function returns state information about the cache instance
include_scriptsInclude script specific state information
Returns an array of information, optionally containing script specific state information, ofalseen caso de error.
Ifopcache.restrict_apiis in use and the current path is in violation of the rule, an E_WARNING will be raised; no status information will be returned.
(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)
opcache_invalidate—Invalidates a cached script
$filename,bool$force=false):boolThis function invalidates a particular script from the opcode cache. Ifforceis unset orfalse, the script will only be invalidated if the modification time of the script is newer than the cached opcodes.
filenameThe path to the script being invalidated.
forceIf set totrue, the script will be invalidated regardless of whether invalidation is necessary.
Returnstrueif the opcode cache forfilenamewas invalidated or if there was nothing to invalidate, orfalseif the opcode cache is disabled.
(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)
opcache_is_script_cached—Tells whether a script is cached in OPCache
$filename):boolThis function checks if a PHP script has been cached in OPCache. This can be used to more easily detect the "warming" of the cache for a particular script.
filenameThe path to the PHP script to be checked.
Returnstrueiffilenameis cached in OPCache,falseotherwise.
(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)
opcache_reset—Resets the contents of the opcode cache
This function resets the entire opcode cache. After callingopcache_reset(), all scripts will be reloaded and reparsed the next time they are hit.
Esta función no tiene parámetros.
Returnstrueif the opcode cache was reset, orfalseif the opcode cache is disabled.
Las funciones del Control de la salida permiten controlar cuándo la salida se evía desde un script. Esto puede ser útil en diferentes situaciones, especialmente si es necesario enviar cabeceras al navegador después de que el script haya comenzado a producir datos. Las funciones del Control de la salida no afectan a las cabeceras enviadas usandoheader()osetcookie(), solamente a las funciones comoechoy a los datos entre bloques de código de PHP.
Nota:
Cuando se actualiza desde PHP 4.1.x (y 4.2.x) a 4.3.x, debido a un error en versones anteriores, ha de asegurarse de que
implicit_flushesté enOFFen el ficherophp.ini, de lo contrario cualquier cosa producida conob_start()no se ocultará desde la salida.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| output_buffering | "0" | PHP_INI_PERDIR | |
| output_handler | NULL | PHP_INI_PERDIR | Disponible desde PHP 4.0.4. |
| implicit_flush | "0" | PHP_INI_ALL | PHP_INI_PERDIR en PHP <= 4.2.3. |
| url_rewriter.tags | "a=href,area=href,frame=src,form=,fieldset=" | PHP_INI_ALL | Disponible desde PHP 4.0.4. Antes de PHP 7.1.0, se usaba para establecer reescriburas de trans sid de sesión. Desde 7.1.0 solamente lo utililzaoutput_add_rewrite_var(). |
| url_rewriter.hosts | $_SERVER['HTTP_HOST']is used as default. | PHP_INI_ALL | Disponible desde PHP 7.1.0 |
He aquí una breve explicación de las directivas de configuración.
output_bufferingboolean/integerSe puede habilitar el búfer de salida para todos los ficheros estableciendo esta directiva a 'On'. Si se necesita limitar el tamaño del búfer a un tamaño en particular, se puede usar un número máximo de bytes en lugar de 'On' como valor para esta directiva (p.ej., output_buffering=4096). A partir de PHP 4.3.5, esta direcitva siempre es 'Off' en PHP-CLI.
output_handlerstringSe pueden redireccionar todas las salidas producidas por los scripts a una funcion. Por ejemplo, si se establece output_handler amb_output_handler(), la codificación de caracteres será convertida de forma transparente a la codificación especificada. Al establecer cualquier gestor de salida automáticamente se activará el búfer de salida.
Nota:
No se puede usarmb_output_handler()conob_iconv_handler(), y tampoco se puedem usar juntosob_gzhandler()yzlib.output_compression.
Nota:
Solamente se pueden usar funciones internas con esta directiva. Para funciones definidas por el usuario se ha de usarob_start().
implicit_flushbooleanEsfalsede forma predeterminada. Cambiarla atruele dirá a PHP que indique a la capa de salida que se vuelque a sí misma automáticamente después de cada bloque de salida. Esto es equivalente a llamar a la función de PHPflush()después de cada llamada aprintoechoy de cada bloque deHTML.
Cuando se usa PHP dentro de un entorno web, la activación de esta opción tiene serias implicaciones de rendimiento, por lo que solamente se recomienda para propósitos de depuración. Este valor estruede forma predeterminada cuando se opera bajo laSAPI CLI.
Véase tambiénob_implicit_flush().
url_rewriter.tagsespecifica qué etiquetas HTML son reescritas por valores deoutput_add_rewrite_var(). Las predeterminadas sona=href,area=href,frame=src,input=src,form=formes una etiqueta especial.<input hidden="id_sesión" name="nombre_sesión">se añade como variable de formulario.Nota:Antes de PHP 7.1.0,url_rewriter.tagsse utilizaba para especificarsession.trans_sid_tags. Desde PHP 7.1.0,
fieldsetya no se considera una etiqueta especial.
url_rewriter.hostsstringurl_rewriter.hostsespecifica los 'hosts' que son reescritos para incluir valores deoutput_add_rewrite_var(). El predeterminado es$_SERVER['HTTP_HOST']. Se pueden especificar varios hosts mediante ",", y no se permiten espacios entre hosts. P.ej.php.net,wiki.php.net,bugs.php.netEsta extensión no tiene ningún tipo de recurso definido.
Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.
PHP_OUTPUT_HANDLER_START(integer)Indica que el almacenamiento en el búfer de salida ha comenzado.
PHP_OUTPUT_HANDLER_WRITE(integer)Indica que el búfer de salida está siendo volcado y tiene datos para producir una salida.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_FLUSH(integer)Indica que el búfer de salida ha sido volcado.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_CLEAN(integer)Indica que el búfer de salida ha sido limpiado.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_FINAL(integer)Indica que esta es la operación final del almacenamiento del búfer de salida.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_CONT(integer)Indica que el búfer de salida ha sido volcado, pero que el almacenamiento en el búfer de salida continurá.
A partir de PHP 5.4, esta constante es un alias dePHP_OUTPUT_HANDLER_WRITE.
PHP_OUTPUT_HANDLER_END(integer)Indica que el almacenamiento del búfer de salida ha finalizado.
A partir de PHP 5.4, esta constante es un alias dePHP_OUTPUT_HANDLER_FINAL.
PHP_OUTPUT_HANDLER_CLEANABLE(integer)Controla si un búfer de salida creado porob_start()puede ser limpiado.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_FLUSHABLE(integer)Controla si un búfer de salida creado porob_start()puede ser volcado.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_REMOVABLE(integer)Controla si un búfer de salida creado porob_start()puede ser eliminado antes de finalizar el script.
Disponible desde PHP 5.4.
PHP_OUTPUT_HANDLER_STDFLAGS(integer)El conjunto predeterminado de banderas de búfer de salida; actualmente equivalente aPHP_OUTPUT_HANDLER_CLEANABLE|PHP_OUTPUT_HANDLER_FLUSHABLE|PHP_OUTPUT_HANDLER_REMOVABLE.
Disponible desde PHP 5.4.
Ejemplo #1 Ejemplo de control de la salida
<?php
ob_start();
echo"Hola\n";
setcookie("nombre_cookie","datos_cookie");
ob_end_flush();
?>En el ejemplo anterior, la salida deechosería almacenada en el búfer de salida hasta que se llamara aob_end_flush(). Mientras tanto, la llamada asetcookie()almacenaría con éxito una cookie sin causar ningún error. (Las cabeceras normalmente no se pueden enviar al navegador después de haber enviado ya los datos.)
Véase tambiénheader()ysetcookie().
(PHP 4, PHP 5, PHP 7, PHP 8)
flush—Vaciar el búfer de salida del sistema
Vacía los búferes de escritura del sistema de PHP y de cualquiera que sea el backend en el que se esté usando PHP (CGI, un servidor web, etc.). Trata de enviar toda la salida producida hasta el momento al navegador, aunque se ha de tener en cuenta algunas cosas.
flush()podría no sobreescribir el esquema del almacenamiento en búfer del servidor web, por lo que no tiene efecto sobre ningún búfer en el lado del cliente del navegador. Tampoco afecta al mecanismo del búfer de salida del espacio de usuario de PHP. Esto significa que se ha de llamar tanto aob_flush()como aflush()para volcar los búferes de salida si se están usando aquellos.
Algunos servidores, especialmente en Win32, seguirán almacenando en búfer la salida producida por un script hasta que éste termine antes de transmitir los resultados al navegador.
Puede que algunos módulos de servidor para Apache, como mod_gzip, usen búferes propios que causarán queflush()no resulte en un envío inmediato de los datos al cliente.
Incluso el navegador puede almacenar en búfer su entrada antes de mostrarla. Netscape, por ejemplo, almacena en búfer el texto hasta que recibe un final de línea o el comienzo de una etiqueta, por lo que no interpretará las tablas hasta que se encuentre la etiqueta </table> de la tabla más externa.
Algunas versiones de Microsoft Internet Explorer solo empezarán a mostrar la página después de que han recibido 256 bytes de salida, por lo que puede que sea necesario enviar espacios en blanco extra antes del volcado para que se muestre la página en tales navegadores.
No devuelve ningún valor.
(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)
ob_clean—Limpiar (eliminar) el búfer de salida
Esta función desecha el contenido del búfer de salida.
Esta función no destruye el búfer de salida como lo haceob_end_clean().
El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_CLEANABLE. Si no,ob_clean()no funcionará.
No devuelve ningún valor.
(PHP 4, PHP 5, PHP 7, PHP 8)
ob_end_clean—Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
Esta función desecha el contenido del búfer de salida en cola y lo desactiva. Si fuera necesario continuar procesando el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_end_clean(), ya que el contenido del búfer es desechado cuando se llama aob_end_clean().
El búfer de salida debe estar iniciado porob_start()con los indicadoresPHP_OUTPUT_HANDLER_CLEANABLEyPHP_OUTPUT_HANDLER_REMOVABLE. Si no,ob_end_clean()no funcionará.
Devuelvetrueen caso de éxito ofalseen caso de error. Entre las posibles razones de un fallo se encuentra llamar a la función sin un búfer activo, o que por algún motivo no se pueda eliminar un búfer (posible en el caso de búferes especiales).
Si la función falla, genera un error de nivelE_NOTICE.
El siguiente ejemplo muestra una forma sencilla de deshacerse de todos los búferes de salida:
Ejemplo #1 Ejemplo deob_end_clean()
<?php
ob_start();
echo'Texto que no será mostrado.';
ob_end_clean();
?>(PHP 4, PHP 5, PHP 7, PHP 8)
ob_end_flush—Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
Esta función enviará el contenido del búfer de salida en cola (si existe) y los deshabilitará. Si fuera necesario procesar el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_end_flush(), ya que el contenido del búfer es descartado después de llamar aob_end_flush().
El búfer de salida debe estar iniciado porob_start()con los indicadoresPHP_OUTPUT_HANDLER_FLUSHABLEyPHP_OUTPUT_HANDLER_REMOVABLESi no,ob_end_flush()no funcionará.
Nota:Esta función es similar aob_get_flush(), excepto queob_get_flush()devuelve el búfer como una cadena de caracteres.
Devuelvetrueen caso de éxito ofalseen caso de error. Entre las posibles razones de un fallo se encuentra llamar a la función sin un búfer activo, o que por algún motivo no se pueda eliminar un búfer (posible en el caso de búferes especiales).
Si la función falla, genera un error de nivelE_NOTICE.
Ejemplo #1 Ejemplo deob_end_flush()
El siguiente ejemplo muestra una forma sencilla de volcar y finalizar todos los búferes de salida:
<?php
while (@ob_end_flush());
?>(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)
ob_flush—Vaciar (enviar) el búfer de salida
Esta función enviará el contenido del búfer de salida (si existe). Si fuera necesario continuar procesando el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_flush(), ya que el contenido del búfer es descartado después de llamar aob_flush().
Esta función no destruye el búfer de salida, como lo haceob_end_flush().
No devuelve ningún valor.
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
ob_get_clean—Obtiene el contenido del búfer actual y elimina el búfer de salida actual
Obtiene el contenido del búfer actual y elimina el búfer de salida actual.
ob_get_clean()básicamente ejecutaob_get_contents()yob_end_clean().
El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_CLEANABLESi no,ob_get_clean()no funcionará.
Devuelve el contenido del búfer de salida y finaliza el almacenamiento en el mismo. Si el almacenamiento en el búfer de salida no está activo, entonces devuelvefalse.
Ejemplo #1 Un ejemplo sencillo deob_get_clean()
<?php
ob_start();
echo"Hola Mundo";
$salida=ob_get_clean();
$salida=strtolower($salida);
var_dump($salida);
?>El resultado del ejemplo sería:
string(10) "hola mundo"
(PHP 4, PHP 5, PHP 7, PHP 8)
ob_get_contents—Devolver el contenido del búfer de salida
Obtiene el contenido del búfer de salida, sin borrarlo.
Devolverá el contenido del búfer de salida, ofalsesi el almacenameinto en el búfer de salida no está activo.
Ejemplo #1 Un ejemplo sencillo deob_get_contents()
<?php
ob_start();
echo"Hola ";
$salida1=ob_get_contents();
echo"Mundo";
$salida2=ob_get_contents();
ob_end_clean();
var_dump($salida1,$salida2);
?>El resultado del ejemplo sería:
string(5) "Hola " string(10) "Hola Mundo"
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
ob_get_flush—Volcar el búfer de salida, devolverlo como una cadena de caracteres y deshabilitar el almacenamiento en el búfer de salida
ob_get_flush()vuelca el búfer de salida, lo devuelve como una cadena de caracteres y deshabilita el almacenamiento en el búfer de salida.
El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_FLUSHABLESi no,ob_get_flush()no funcionará.
Nota:Esta función es similar aob_end_flush(), excepto que esta función además devuelve el búfer como una cadena de caracteres.
Devuelve el búfer de salida, ofalsesi el almacenamiento en el búfer no está activo.
Ejemplo #1 Ejemplo deob_get_flush()
<?php
//usar output_buffering=On
print_r(ob_list_handlers());
//guardar el búfer en un fichero
$búfer=ob_get_flush();
file_put_contents('bufer.txt',$búfer);
print_r(ob_list_handlers());
?>El resultado del ejemplo sería:
Array
(
[0] => default output handler
)
Array
(
)
(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)
ob_get_length—Devolver la longitud del búfer de salida
Esta función devolverá la longitud del contenido del búfer de salida, en bytes.
Devuelve la longitud del contenido del búfer de salida, en bytes, ofalsesi no está activo el almacenamiento en búfer.
Ejemplo #1 Un ejemplo sencillo deob_get_length()
<?php
ob_start();
echo"Hola ";
$longitud1=ob_get_length();
echo"Mundo";
$longitud2=ob_get_length();
ob_end_clean();
echo$longitud1.", .".$longitud2;
?>El resultado del ejemplo sería:
5, 10
(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)
ob_get_level—Devolver el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida
Devuelve el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida.
Devuelve el nivel de los gestores de almacenamiento en búfer de salida anidados, o cero si el almacenamiento en búfer no está activo.
(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)
ob_get_status—Obtener el estado de los búferes de salida
$full_status= FALSE):arrayob_get_status()devuelve la información de estado sobre el búfer de salida de nivel superior, o sobre todos los niveles activos de búferes de salida sifull_statuses establecido atrue.
full_statustruepara devolver todos los niveles de búferes de salida activos. Si esfalseo no se establece, solo es devuelto el búfer de salida de nivel más alto.
Si esta función es llamada sin el parámetrofull_status, o confull_status=false, se devuelve un único array con los siguientes elementos:
Array
(
[level] => 2
[type] => 0
[status] => 0
[name] => URL-Rewriter
[del] => 1
)| Clave | Valor |
|---|---|
| level | Nivel de anidamiento de la salida |
| type | PHP_OUTPUT_HANDLER_INTERNAL(0)oPHP_OUTPUT_HANDLER_USER (1) |
| status | Un valor entrePHP_OUTPUT_HANDLER_START(0),PHP_OUTPUT_HANDLER_CONT(1) oPHP_OUTPUT_HANDLER_END(2) |
| name | Nombre del gestor de salida activo, o 'default output handler' si no hay uno establecido |
| del | Bandera de borrado, tal y como está establecido porob_start() |
Si se llama confull_status=true, se devuelve un array con un elemento por cada nivel de búfer de salida activo. El nivel de salida se usa como la clave del array de nivel superior, y cada elemento del array en sí es otro array que contiene información de estado sobre un nivel de salida activo.
Array
(
[0] => Array
(
[chunk_size] => 0
[size] => 40960
[block_size] => 10240
[type] => 1
[status] => 0
[name] => default output handler
[del] => 1
)
[1] => Array
(
[chunk_size] => 0
[size] => 40960
[block_size] => 10240
[type] => 0
[buffer_size] => 0
[status] => 0
[name] => URL-Rewriter
[del] => 1
)
)
La salida completa contiene los siguientes elementos adicionales:
| Clave | Valor |
|---|---|
| chunk_size | Tamaño del segmento, tal y como es establecido porob_start() |
| size | ... |
| blocksize | ... |
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
ob_gzhandler—Función de llamada de retorno de ob_start para comprimir el búfer de salida con gzip
$buffer,int$mode):stringob_gzhandler()tiene por objeto usarse como una función de llamada de retorno paraob_start()para facilitar en envío de datos codificados con gz a los navegadores web que admiten la compresión de páginas web. Antes de queob_gzhandler()realmente envíe datos comprimidos, determina el tipo de codificación de contenido que aceptará el navegador ("gzip", "deflate" o ninguno) y devolverá su salida en consecuencia. Se admiten todos los navegadores, ya que es responsabilidad de los mismos enviar la cabecera correcta que indique que acepta páginas web comprimidas. Si un navegador no admite páginas comprimidas, esta función devolveráfalse.
buffermodeEjemplo #1 Ejemplo deob_gzhandler()
<?php
ob_start("ob_gzhandler");
?>
<html>
<body>
<p>Esta debería ser una página comprimida.</p>
</body>
</html>Nota:
ob_gzhandler()requiere la extensiónzlib.
Nota:
No se pueden usar juntosob_gzhandler()yzlib.output_compression. Observe también que se prefiere el uso dezlib.output_compressionantes queob_gzhandler().
(PHP 4, PHP 5, PHP 7, PHP 8)
ob_implicit_flush—Habilitar/deshabilitar el volcado implícito
$flag= true):voidob_implicit_flush()habilitará o deshabilitará el volcado implícito. El volcado implícito resultará en una operación de volcado después de cada llamada que produzca salida, de modo que no son necesarias las llamadas explícitas aflush().
flagtruepara habilitar el volcado implícito,falsepara deshabilitarlo.
No devuelve ningún valor.
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
ob_list_handlers—Enumerar todos los gestores de salida en uso
Enumera todos los gestores de salida en uso.
Esta función devolverá un array con los gestores de salida en uso (si existen). Sioutput_bufferingestá habilitado o se usó una función anónima conob_start(),ob_list_handlers()devolverá "default output handler" (gestor de salida predeterminado).
Ejemplo #1 Ejemplo deob_list_handlers()
<?php
//usando output_buffering=On
print_r(ob_list_handlers());
ob_end_flush();
ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();
// funciones anónimas
ob_start(function($string) { return$string; });
print_r(ob_list_handlers());
ob_end_flush();
?>El resultado del ejemplo sería:
Array
(
[0] => default output handler
)
Array
(
[0] => ob_gzhandler
)
Array
(
[0] => Closure::__invoke
)
(PHP 4, PHP 5, PHP 7, PHP 8)
ob_start—Activa el almacenamiento en búfer de la salida
$output_callback=null,int$chunk_size= 0,int$flags=PHP_OUTPUT_HANDLER_STDFLAGS):boolEsta función activará el almacenamiento en búfer de la salida. Mientras dicho almacenamiento esté activo, no se enviará ninguna salida desde el script (aparte de cabeceras); en su lugar la salida se almacenará en un búfer interno.
El contenido de este búfer interno se puede copiar a una variable de tipo string usandoob_get_contents(). Para producir la salida de lo almacenado en el búfer interno se ha de usarob_end_flush(). De forma alternativa,ob_end_clean()desechará de manera silenciosa el contenido del búfer.
Algunos servidores web (p.ej. Apache) cambian en directorio de trabajo de un script cuando se invoca a la función de llamada de retorno. Se puede cambiar de nuevo mediante, por ejemplo,chdir(dirname($_SERVER['SCRIPT_FILENAME']))en la función de llamada de retorno.
Los búferes de salida son apilables, es decir, que se podría llamar aob_start()mientras otroob_start()esté activo. Se ha de asegurar llamar aob_end_flush()las veces apropiadas. Si están activas múltiples funciones de llamada de retorno de salida, la salida se filtrará secuencialmente por cada una de ellas en orden de anidamiento.
output_callbackSe puede especificar una funciónoutput_callbackopcional. Esta función toma un string como parámetro y debería devolver otro string. La función se llamará cuando el búfer de salida sea volcado (enviado), limpiado (conob_flush(),ob_clean()o alguna función similar) o cuando el búfer de salida sea volcado al navegador al final de la petición. Cuando se llame aoutput_callback, ésta recibirá el contenido del búfer de salida como su propio parámetro, y se espera que devuelva un nuevo búfer de salida como resultado, que será enviado al navegador. Sioutput_callbackno es una función llamable, esta función devolveráfalse. Esta es la firma de la llamada de retorno:
$buffer,int$phase= ?):stringbufferphasePHP_OUTPUT_HANDLER_*.Sioutput_callbackdevuelvefalse, se enviará la entrada original al navegador.
El parámetrooutput_callbackse puede omitir pasando un valornull.
ob_end_clean(),ob_end_flush(),ob_clean(),ob_flush()yob_start()no se pueden llamar desde una función de llamada de retorno. Si se hace, el comportamiento no estará definido. Si se quiere borrar el contenido de un búfer, se ha de devolver "" (un string nulo) desde la función de llamada de retorno. Tampoco se pueden llamar a funciones usando las funciones de búfer de salida comoprint_r($expresión, true)ohighlight_file($nombre_fichero, true)desde una función de llamada de retorno.
Nota:
En PHP 4.0.4,ob_gzhandler()se introdujo para facilitar el envío de datos codificados con gz a los navegadores web que admitan páginas web comprimidas.ob_gzhandler()determima el tipo de codificación de contenido que aceptará el navegador y devolverá su salida en consecuencia.
chunk_sizeSi se proporciona el parámetro opcionalchunk_size, el búffer será volcado después de cualquier llamada de salida que cause que la longitud del búfer sea igual o exceda achunk_size. El valor predeterminado0significa que la función de salida será llamada únicamente cuando el búfer de salida se cierre.
Antes de PHP 5.4.0, el valor1era un caso especial que establecía el tamaño de segmento a 4096 bytes.
flagsEl parámetroflagses una máscara de bits que controla las operaciones que se pueden realizar sobre el búfer de salida. Lo predeterminado es permitir que los búferes de salida sean limpiados, volcados y borrados, lo que se puede hacer explícitamente mediantePHP_OUTPUT_HANDLER_CLEANABLE|PHP_OUTPUT_HANDLER_FLUSHABLE|PHP_OUTPUT_HANDLER_REMOVABLE, oPHP_OUTPUT_HANDLER_STDFLAGScomo clave.
Cada bandera (flag) controla el acceso a un conjunto de funciones, como está descrito a continuación:
| Constante | Funciones |
|---|---|
PHP_OUTPUT_HANDLER_CLEANABLE | ob_clean(),ob_end_clean(), yob_get_clean(). |
PHP_OUTPUT_HANDLER_FLUSHABLE | ob_end_flush(),ob_flush(), yob_get_flush(). |
PHP_OUTPUT_HANDLER_REMOVABLE | ob_end_clean(),ob_end_flush(), yob_get_flush(). |
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 7.0.0 | En caso de utilizarob_start()dentro de una retrollamada del búfer de salida, esta función ya no emitirá unE_ERROR, si no unE_RECOVERABLE_ERROR, permitiendo a los manejadores de errores propios capturar tales errores. |
| 5.4.0 | El tercer parámetro deob_start()se cambió de un parámetrobooleanllamadoerase(el cual, si se establecía afalse, prevenía al búfer de salida de ser eliminado hasta el final de la ejecución del script) a un parámetrointegerllamadoflags. Desafortunadamente, esto resulta en una rotura de compatibilidad de la API para código escrito antes de PHP 5.4.0 que use el tercer parámetro. Véaseel ejemplo de banderaspara saber cómo manejar esto con código que necesite ser compatible con ambas. |
| 5.4.0 | Un tamaño de segmento de1ahora resulta en segmentos de 1 byte que se van a enviar al búfer de salida. |
| 4.3.2 | Se modficó esta función que devuelvafalseen caso de que la funciónoutput_callbackpasada no pueda ejecutarse. |
Ejemplo #1 Ejemplo de una función de llamada de retorno definida por el usuario
<?php
functioncallback($búfer)
{
// reemplazar todas las manzanas por naranjas
return (str_replace("manzanas","naranjas",$búfer));
}
ob_start("callback");
?>
<html>
<body>
<p>Es como comparar manzanas con naranjas.</p>
</body>
</html>
<?php
ob_end_flush();
?>El resultado del ejemplo sería:
<html> <body> <p>Es como comparar naranjas con naranjas.</p> </body> </html>
Ejemplo #2 Crear un búfer de salida imborrable de forma compatible con PHP 5.3 y 5.4
<?php
if (version_compare(PHP_VERSION,'5.4.0','>=')) {
ob_start(null,0,PHP_OUTPUT_HANDLER_STDFLAGS^
PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
ob_start(null,0,false);
}
?>(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
output_add_rewrite_var—Añadir valores al mecanismo de reescritura de URLs
$name,string$value):boolEsta función añade otro par nombre/valor al mecanismo de reescritura de URLs. El nombre y el valor se agregarán a los URLs (como parámetros de GET) y a los formularios (como camos intput ocultos) de la misma forma que el ID de sesión cuando la reescritura de URLs de forma transparente está habilitada consession.use_trans_sid. Observe que los URLs absolutos (http://example.com/..) no son reescritos.
El comportamiento de esta función está controlado por el parámetrourl_rewriter.tagsdephp.ini.
Nota:Al llamar a esta función se iniciará el almacenamiento implícito en búfer de salida si no estaba ya activo.
nameEl nombre de la variable.
valueEl valor de la variable.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo deoutput_add_rewrite_var()
<?php
output_add_rewrite_var('var','valor');
// algunos enlaces
echo'<a href="fichero.php">enlace</a>
<a href="http://example.com">enlace2</a>';
// un formulario
echo'<form action="script.php" method="post">
<input type="text" name="var2" />
</form>';
print_r(ob_list_handlers());
?>El resultado del ejemplo sería:
<a href="fichero.php?var=valor">enlace</a>
<a href="http://example.com">enlace2</a>
<form action="script.php" method="post">
<input type="hidden" name="var" value="valor" />
<input type="text" name="var2" />
</form>
Array
(
[0] => URL-Rewriter
)
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
output_reset_rewrite_vars—Restablecer los valores del mecanismo de reescritura de URLs
Esta función restablece el mecanismo de reescritura de URLs y elimina todas las variables de reescritura establecidas previamente por la funciónoutput_add_rewrite_var().
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 7.1.0 | Antes de PHP 7.1.0, la variables reescritas poroutput_add_rewrite_var()utilizaban el mismo buffer de salida del módulo de sesión trans sid. Desde PHP 7.1.0, se usa un buffer de salida dedicado youtput_reset_rewrite_vars()solo elimina las variables reescritas definidas poroutput_add_rewrite_var(). |
Ejemplo #1 Ejemplo deoutput_reset_rewrite_vars()
<?php
session_start();
output_add_rewrite_var('var','value');
echo'<a href="file.php">link</a>';
ob_flush();
output_reset_rewrite_vars();
echo'<a href="file.php">link</a>';
?>El resultado del ejemplo sería:
<a href="file.php?PHPSESSID=xxx&var=value">link</a> <a href="file.php">link</a>
Estas funciones permiten obtener mucha información sobre PHP, p.ej., configuración en tiempo de ejecución, extensiones en uso, versión, y mucho más. También se pueden encontrar funciones para establecer opciones al ejecutar PHP. Aquí se puede encontrar la función probablemente más conocida de PHP -phpinfo()-.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| assert.active | "1" | PHP_INI_ALL | |
| assert.bail | "0" | PHP_INI_ALL | |
| assert.warning | "1" | PHP_INI_ALL | |
| assert.callback | NULL | PHP_INI_ALL | |
| assert.quiet_eval | "0" | PHP_INI_ALL | |
| assert.exception | "0" | PHP_INI_ALL | Disponible desde PHP 7.0.0. |
| enable_dl | "1" | PHP_INI_SYSTEM | Esta característica obsoletaseráeliminadacon certeza en el futuro. |
| max_execution_time | "30" | PHP_INI_ALL | |
| max_input_time | "-1" | PHP_INI_PERDIR | Disponible desde PHP 4.3.0. |
| max_input_nesting_level | "64" | PHP_INI_PERDIR | Disponible desde PHP 4.4.8. y PHP 5.2.3. |
| max_input_vars | 1000 | PHP_INI_PERDIR | Available since PHP 5.3.9. |
| magic_quotes_gpc | "1" | PHP_INI_PERDIR | PHP_INI_ALL en PHP <= 4.2.3. Eliminado en PHP 5.4.0 |
| magic_quotes_runtime | "0" | PHP_INI_ALL | Eliminado en PHP 5.4.0 |
| zend.enable_gc | "1" | PHP_INI_ALL | Disponible desde PHP 5.3.0. |
He aquí una breve explicación de las directivas de configuración.
assert.activebooleanActiva la evaluación deaserciones().
assert.bailbooleanTerminar la ejecución del script si falla una aserción.
assert.warningbooleanLanzar un PHP warning for cada aserción que falle.
assert.callbackstringFunción de usuario a llamar cuando fallen las aserciones.
assert.quiet_evalbooleanUsar la configuración actual deerror_reporting()durante las expresiones de evaluación de aserciones. Si está habilitado, no se mostrarán errores (incondicional error_reporting(0)) durante evaluación. Si está deshabitado, se mostrarán errores según la configuración deerror_reporting()
assert.exceptionbooleanEmite una excepciónAssertionErrorpara la afirmación fallida.
enable_dlbooleanEsta directiva es muy útil solamente en la versión PHP con el módulo Apache. Se puede activar o desactivar la carga dinámica de extensiones PHP condl()por servidor virtual o directorio.
La razón principal para desactivar la carga dinámica es por seguridad. Con la carga dinámica, es posible ignorar todas las restriccionesopen_basedir. De forma predeterminada se permite la carga dinámica.
max_execution_timeintegerEste valor establece el tiempo máximo en segundos que se permite ejecutar antes de que el analizador termine. Esto ayuda a prevenir que scripts mal escritos bloqueen el servidor. El valor por defecto es30. Cuando se ejecuta PHP desde lalínea de comandosel valor por defecto es0.
El tiempo de ejecución máxima no está afectada por llamadas al sistema, operaciones de stream etc. Por favor véase la funciónset_time_limit()para más información.
El servidor web puede tener otras configuraciones de tiempo de espera que quizá interrumpan la ejecución de PHP. Apache tiene la directivaTimeouty IIS tiene la función CGI timeout. Las dos de 300 segundos por omisión. Véase la documentación del servidor web para información específica.
max_input_timeintegerEstablece el tiempo máximo en segundos que se permite a un script analizar datos de entrada, como POST y GET. La medición comienza en el momento en que PHP es invocado en el servidor y finaliza cuando la ejecución comienza.
max_input_nesting_levelintegerEstablece el máximo de profundidad de anidamiento paravariables de entrada(p.ej.$_GET,$_POST.)
max_input_varsintegerCuantasvariables de entradapueden ser aceptadas (el límite se aplica a los arrays superglobales $_GET, $_POST y $_COOKIE de forma separada). El uso de esta directiva mitiga la posibilidad de ataques de denegación de servicio que utilizan colisiones de hash. Si hay más variables de entrada que las especificadas por la presente directiva, unE_WARNINGes emitido, y otras variables entrada son truncadas a partir de la solicitud.
magic_quotes_gpcbooleanEsta característica ha sido declaradaOBSOLETAdesde PHP 5.3.0 yELIMINADAa partir de PHP 5.4.0.
Establece las magic_quotes state para operaciones GPC (Get/Post/Cookie). Cuando las magic_quotes están activadas, todas las ' (comillas simples), " (comillas dobles), \ (barra invertida) y NUL's son escapados con una barra invertida de forma automática..
Ver tambiénget_magic_quotes_gpc()
magic_quotes_runtimebooleanEsta característica ha sido declaradaOBSOLETAdesde PHP 5.3.0 yELIMINADAa partir de PHP 5.4.0.
Simagic_quotes_runtimeestá activado, la mayoría de funciones que devuelven datos desde cualquier tipo de recurso externo incluyendo bases de datos y ficheros de texto contendrán comillas escapadas con barras invertidas.
Funciones afectadas pormagic_quotes_runtime(no incluye funciones de PECL):
zend.enable_gcbooleanHabilita o deshabilita el colector de referencia circular.
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.
| Constante | Valor | Descripción |
|---|---|---|
CREDITS_GROUP | 1 | Lista de los desarrolladores del núcleo |
CREDITS_GENERAL | 2 | Créditos generales: Diseño del lenguaje y concepto, autores de PHP y módulos SAPI. |
CREDITS_SAPI | 4 | Lista de los módulos API para PHP y sus autores. |
CREDITS_MODULES | 8 | Lista de los módulos de extensión para PHP y sus autores. |
CREDITS_DOCS | 16 | Los créditos del equipo de documentación. |
CREDITS_FULLPAGE | 32 | Normalmente se utiliza en combiación con otras opciones.Indica que una página HTML independiente debe ser mostrada incluyendo la información indicada por otras opciones. |
CREDITS_QA | 64 | Los créditos del equipo de testers. |
CREDITS_ALL | -1 | Todos los créditos, es equivalente a usar:CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_QA CREDITS_FULLPAGE. Genera una página HTML independiente con las apropiadas etiquetas. Este es el valor por defecto. |
| Constante | Valor | Descripción |
|---|---|---|
INFO_GENERAL | 1 | La línea de comandos de configuración,php.iniruta, fecha del build, servidor Web, sistema y demás. |
INFO_CREDITS | 2 | Créditos de PHP. Ver tambiénphpcredits(). |
INFO_CONFIGURATION | 4 | Valores locales y maestros actuales para directivas PHP. Ver tambiénini_get(). |
INFO_MODULES | 8 | Módulos cargados y sus respectivas opciones. |
INFO_ENVIRONMENT | 16 | Información de variables de entorno, también está disponible en$_ENV. |
INFO_VARIABLES | 32 | Muestra todas lasvariables predefinidasdesdeEGPCS(Entorno, GET, POST, Cookie, Server). |
INFO_LICENSE | 64 | Información de la licencia de PHP. Ver también» FAQ de la licencia. |
INFO_ALL | -1 | Muestra todas las directivas que se han indicado hasta ahora. Este es el valor por defecto. |
| Constante | Valor | Descripción |
|---|---|---|
INI_USER | 1 | Sin uso |
INI_PERDIR | 2 | Sin uso |
INI_SYSTEM | 4 | Sin uso |
INI_ALL | 7 | Sin uso |
Constantes de aserción, estos valores se usan para definir opciones de aserción enassert_options().
| Constante | Opción INI | Descripción |
|---|---|---|
ASSERT_ACTIVE | assert.active | Habilita la evaluación deassert(). |
ASSERT_CALLBACK | assert.callback | Llamada de retorno a llamar en caso que falle la aserción. |
ASSERT_BAIL | assert.bail | Terminar la ejecucción al finalizar aserciones. |
ASSERT_WARNING | assert.warning | Genera un warning PHP por cada aserción que falle |
ASSERT_QUIET_EVAL | assert.quiet_eval | Desactivaerror_reportingdurante la evaluación de expresiones de aserción. |
Las siguientes constantes están disponibles únicamente si se está ejecutando el sistema operativo Windows y muestran información sobre las diferentes versiones. Esto hace posible el detectar determinadas características para poder hacer uso de ellas. Disponibles desde PHP 5.3.0.
| Constante | Descripción |
|---|---|
PHP_WINDOWS_VERSION_MAJOR | El número mayor de la versión de Windows, que puede tener el valor4(NT4/Me/98/95),5(XP/2003 R2/2003/2000) o6(Vista/2008/7/8/8.1). |
PHP_WINDOWS_VERSION_MINOR | El número menor de la versión de Windows, que puede tener el valor0(Vista/2008/2000/NT4/95),1(XP),2(2003 R2/2003/XP x64),10(98) o90(ME). |
PHP_WINDOWS_VERSION_BUILD | El número del build de Windows (por ejemplo, Windows Vista con SP1 sería el build número 6001) |
PHP_WINDOWS_VERSION_PLATFORM | La plataforma en la que PHP se está ejecutando, su valor es2en Windows Vista/XP/2000/NT4, Server 2008/2003 y en Windows ME/98/95 su valor es1. |
PHP_WINDOWS_VERSION_SP_MAJOR | El número mayor de la versión del service pack instalado, su valor es0si no hay ningún service pack instalado. Por ejemplo, Windows XP con service pack 3 instalado hará que el valor sea3. |
PHP_WINDOWS_VERSION_SP_MINOR | El número menor de la versión del service pack instalado, su valor es0si no hay ningún service pack instalado. |
PHP_WINDOWS_VERSION_SUITEMASK | El suitemask es una máscara de bits que puede indicar si determinadas características de Windows están instaladas, consulte la siguiente tabla para ver los diferentes valores del campo de bits. |
PHP_WINDOWS_VERSION_PRODUCTTYPE | Contiene el valor usado para determinar las constantesPHP_WINDOWS_NT_*. Este valor puede ser una de las constantesPHP_WINDOWS_NT_*que indica el tipo de sistema que se está usando. |
PHP_WINDOWS_NT_DOMAIN_CONTROLLER | El controlador de dominio |
PHP_WINDOWS_NT_SERVER | El servidor del sistema (ej. Server 2008/2003/2000), observe que si es un controlador de dominio será informado comoPHP_WINDOWS_NT_DOMAIN_CONTROLLER. |
PHP_WINDOWS_NT_WORKSTATION | Es una estación de trabajo (pej. Vista/XP/2000/NT4) |
Esta tabla muestra una lista de características que pueden ser comprobadas al usar la máscara de bitsPHP_WINDOWS_VERSION_SUITEMASK.
| Bits | Descripción |
|---|---|
0x00000004 | Los componentes de Microsoft BackOffice están instalados. |
0x00000400 | Windows Server 2003, Web Edition está instalado. |
0x00004000 | Windows Server 2003, Compute Cluster Edition está instalado. |
0x00000080 | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition o Windows 2000 Datacenter Server está instalado. |
0x00000002 | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, o Windows NT Server 4.0 Enterprise Edition está instalado. |
0x00000040 | Windows XP Embedded está instalado. |
0x00000200 | Windows Vista Home Premium, Windows Vista Home Basic, o Windows XP Home Edition está instalado. |
0x00000100 | Escritorio remoto habilitado, limitado a una sesión interactiva. Este valor está definido a no ser que el sistema se ejecute en modo de servidor de aplicaciones. |
0x00000001 | Microsoft Small Business Server fue instalado en el sistema, pero quizá ha sido actualizado a otra versión de Windows. |
0x00000020 | Microsoft Small Business Server está instalado con la restricción de licencia en vigor. |
0x00002000 | Windows Storage Server 2003 R2 o Windows Storage Server 2003 está instalado. |
0x00000010 | Terminal Services está instalado. Este valor siempre está definido. En caso que lo esté pero0x00000100no, entonces el sistema estará ejecutándose en modo de servidor de aplicaciones. |
0x00008000 | Windows Home Server está instalado. |
(PHP 4, PHP 5, PHP 7, PHP 8)
assert_options—Establecer/obtener valores de las directivas relacionadas con las aserciones
Se utiliza para establecer el valor de las diferentes opciones de la funciónassert()o consultar su valor actual.
what| Opción | Configuración inicial | Valor predeterminado | Descripción |
|---|---|---|---|
| ASSERT_ACTIVE | assert.active | 1 | Activa la funciónassert() |
| ASSERT_WARNING | assert.warning | 1 | Cada vez que una aserción falla se genera una advertencia |
| ASSERT_BAIL | assert.bail | 0 | Termina la ejecución cuando falla una aserción |
| ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | Desactiva la directiva error_reporting durante la evaluación de la aserción |
| ASSERT_CALLBACK | assert.callback | (null) | Función que se encargará de gestionar las aserciones cuando fallen |
valueNuevo valor para la directiva.
Devuelve el valor original de cualquiera de las opciones ofalseen caso de error.
Ejemplo #1 Ejemplo deassert_options()
<?php
// Esta es nuestra función manejadora
// de los fallos en un aserción
functionassert_failure()
{
echo'Assert failed';
}
// Esta es nuestra función de test
functiontest_assert($parameter)
{
assert(is_bool($parameter));
}
// Establecemos nuestras propias opciones para gestionar las aserciones
// Activamos las aserciones
assert_options(ASSERT_ACTIVE,true);
// Si una aserción falla se detiene la ejecución
assert_options(ASSERT_BAIL,true);
// Si una aserción falla NO se genera una advertencia
assert_options(ASSERT_WARNING,false);
// Establecemos la función 'assert_failure' como manejadora (callback) de las aserciones
assert_options(ASSERT_CALLBACK,'assert_failure');
// Creamos una aserción la cual queremos que falle
test_assert(1);
// Este código nunca se ejecuta porque ASSERT_BAIL
// está a TRUE
echo'Never reached';
?>(No version information available, might only be in Git)
Aserción—Verifica si la aserción esfalse
PHP 5 y 7
PHP 7
La funciónassert()revisará el parámetroassertionproporcionado y tomará la acción apropiada si su resultado esfalse.
Si el parámetroassertiones proporcionado como un string será evaluado como código PHP por la funciónassert(). Las ventajas de un parámetroassertioncomo string es que son menos sobrecargados cuando la comprobación de la aserción está deshabilitada y los mensajes que contienen la expresiónassertion, la expresión falla. Esto significa que si pasa una condición de tipo boolean comoassertionesta condición no se mostrará como parámetro a la función de aserción la cual tiene que haber definido con la funciónassert_options(), la condición es convertida a un string antes de llamar ese manejador de función, y el tipo booleanfalsees convertido como el string vacío.
Las aserciones deberían ser utilizadas solamente como una característica de depuración. Debería utilizarlas para las revisiones de buen funcionamiento las cuales comprueban las condiciones que siempre deberían sertruey que indican algunos errores de programación o si no, para revisar la presencia de algunas características, como funciones de extensión o ciertos límites del sistema y características.
Las aserciones no deberían utilizarse para operaciones normales en tiempo de ejecución como revisiones de parámetros de entrada. Como regla general su código siempre debería ser capaz de funcionar correctamente aún si la verificación de aserción no está activada.
El comportamiento de la funciónassert()podría ser configurado por la funciónassert_options()o por .ini-settings el cual está descrito en la página del manual de esas funciones.
La funciónassert_options()y/o la directiva de configuraciónASSERT_CALLBACKpermite que una función de llamada de retorno sea establecida para manejar aseciones fallidas.
Las llamadas de retornoassert()son particularmente útiles para construir conjuntos de pruebas automatizadas porque le permiten capturar fácilmente el código pasado a la aserción, junto con la información en donde fue hecha la aserción. Mientras que la información puede ser capturada a través de otros métodos, utilizar asernciones lo hace mucho más rápido y más fácil!
La función de llamada de retorno debería aceptar tres argumentos. El primero contendrá el fichero en que falló la aserción. El segundo contendrá la línea en la que falló la aserción y el tercer argumento contendrá la expresión que falló (si la hubiera — valores literales tales como 1 o "dos" no se pasarán a través de este argumento). Los usuarios de PHP 5.4.8 y versiones posteriores también podrían proveer un cuarto argumento opcional, que contendrá el parámetrodescriptionproporcionado a la funciónassert(), si fue establecido.
La funciónassert()es una construcción de lenguaje en PHP 7, que permite la definición de expectativas: las aserciones que surten efecto en ambientes de desarrollo y pruebas, pero que se optimizan para que tengan costo cero en la producción.
************* desde aqui *************** Mientras queassert_options()puede ser utilizada para controlar el comportamiento como se describe anteriormente por la compatibilidad con versiones anteriores, el código PHP 7 sólo debería usar las dos directivas nuevas de configuración para controlar el comportamiento deassert()y no llamar aassert_options().
| Directive | Default value | Possible values |
|---|---|---|
| zend.assertions | 1 |
|
| assert.exception | 0 |
|
assertionThe assertion. In PHP 5, this must be either astringto be evaluated or abooleanto be tested. In PHP 7, this may also be any expression that returns a value, which will be executed and the result used to indicate whether the assertion succeeded or failed.
descriptionAn optional description that will be included in the failure message if theassertionfails.
exceptionIn PHP 7, the second parameter can be aThrowableobject instead of a descriptivestring, in which case this is the object that will be thrown if the assertion fails and theassert.exceptionconfiguration directive is enabled.
falseif the assertion is false,trueotherwise.
| Versión | Descripción |
|---|---|
| 7.0.0 | assert()is now a language construct and not a function.assertion()can now be an expression. The second parameter is now interpreted either as anexception(if aThrowableobject is given), or as thedescriptionsupported from PHP 5.4.8 onwards. |
| 5.4.8 | Thedescriptionparameter was added. Thedescriptionis also now provided to a callback function inASSERT_CALLBACKmode as the fourth argument. |
Ejemplo #1 Handle a failed assertion with a custom handler
<?php
// Active assert and make it quiet
assert_options(ASSERT_ACTIVE,1);
assert_options(ASSERT_WARNING,0);
assert_options(ASSERT_QUIET_EVAL,1);
// Create a handler function
functionmy_assert_handler($file,$line,$code)
{
echo"<hr>Assertion Failed:
File '$file'<br />
Line '$line'<br />
Code '$code'<br /><hr />";
}
// Set up the callback
assert_options(ASSERT_CALLBACK,'my_assert_handler');
// Make an assertion that should fail
assert('mysql_query("")');
?>Ejemplo #2 Using a custom handler to print a description
<?php
// Active assert and make it quiet
assert_options(ASSERT_ACTIVE,1);
assert_options(ASSERT_WARNING,0);
assert_options(ASSERT_QUIET_EVAL,1);
// Create a handler function
functionmy_assert_handler($file,$line,$code,$desc=null)
{
echo"Assertion failed at$file:$line:$code";
if ($desc) {
echo":$desc";
}
echo"\n";
}
// Set up the callback
assert_options(ASSERT_CALLBACK,'my_assert_handler');
// Make an assertion that should fail
assert('2 < 1');
assert('2 < 1','Two is less than one');
?>El resultado del ejemplo sería:
Assertion failed at test.php:21: 2 < 1 Assertion failed at test.php:22: 2 < 1: Two is less than one
Ejemplo #3 Expectations without a custom exception
<?php
assert(true==false);
echo'Hi!';
?>Withzend.assertionsset to 0, the above example will output:
Hi!
Withzend.assertionsset to 1 andassert.exceptionset to 0, the above example will output:
Warning: assert(): assert(true == false) failed in - on line 2 Hi!
Withzend.assertionsset to 1 andassert.exceptionset to 1, the above example will output:
Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
thrown in - on line 2
Ejemplo #4 Expectations with a custom exception
<?php
classCustomErrorextendsAssertionError{}
assert(true==false, newCustomError('True is not false!'));
echo'Hi!';
?>Withzend.assertionsset to 0, the above example will output:
Hi!
Withzend.assertionsset to 1 andassert.exceptionset to 0, the above example will output:
Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!
Withzend.assertionsset to 1 andassert.exceptionset to 1, the above example will output:
Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
thrown in - on line 4
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
cli_get_process_title—Returns the current process title
Returns the current process title, as set bycli_set_process_title(). Note that this may not exactly match what is shown inpsortop, depending on your operating system.
This function is available only inCLImode.
Esta función no tiene parámetros.
Return a string with the current process title ornullon error.
AnE_WARNINGwill be generated if the operating system is unsupported.
Ejemplo #1cli_get_process_title()example
<?php
echo"Process title: ".cli_get_process_title() ."\n";
?>(PHP 5 >= 5.5.0, PHP 7, PHP 8)
cli_set_process_title—Sets the process title
$title):boolSets the process title visible in tools such astopandps. This function is available only inCLImode.
titleThe new title.
Devuelvetrueen caso de éxito ofalseen caso de error.
AnE_WARNINGwill be generated if the operating system is unsupported.
Ejemplo #1cli_set_process_title()example
<?php
$title="My Amazing PHP Script";
$pid=getmypid();// you can use this to see your process title in ps
if (!cli_set_process_title($title)) {
echo"Unable to set process title for PID$pid...\n";
exit(1);
} else {
echo"The process title '$title' for PID$pidhas been set for your process!\n";
sleep(5);
}
?>(PHP 4, PHP 5, PHP 7, PHP 8)
dl—Carga una extensión de PHP durante la ejecución
$library):boolCarga la extensión PHP dada por el parámetrolibrary.
Utilice la funciónextension_loaded()para comprobar si la extensión ya está cargada o no. Funciona tanto para extensiones ya integradas en PHP o para extensiones que se han cargado dinámicamente (ya sea a través dephp.iniodl()).
Esta función ha sido eliminada de la mayoría de las SAPI en PHP 5.3.0, y de PHP-FPM en PHP 7.0.0.
libraryEste parámetro essolamenteel fichero de la extensión a cargar el cual depende del sistema operativo. Por ejemplo, la extensiónsockets(si se compila como librería, no como parte de PHP) Se llamarásockets.soen sistemas Unix mientras que en Windows se llamaráphp_sockets.dll.
El directorio desde donde la extensión será cargada también depende del sistema operativo:
En Windows - a no ser que se defina explicitamente enphp.ini, la extensión será cargada por defecto desdeC:\php4\extensions\(PHP4) oC:\php5\en (PHP 5).
Unix - a no ser que se defina enphp.ini, el directorio de extensiones por defecto depende de
--enable-debugo noZEND_MODULE_API_NO(Número interno del API Zend, que es básicamente la fecha en que se produjo un cambio de versión, p.ej.20010901)<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO, p.ej./usr/local/php/lib/php/extensions/debug-non-zts-20010901o/usr/local/php/lib/php/extensions/no-debug-zts-20010901.Devuelvetrueen caso de éxito ofalseen caso de error. Si la funcionalidad de cargar módulos no está disponible o ha sido deshabilitada (ya sea activandoenable_dloff enphp.ini) Se producirá unE_ERRORy se parará la ejecucción de PHP. Sidl()falló porque la librería especificacda no pudo cargarse a demás defalsese producirá un mensajeE_WARNING.
Ejemplo #1 Ejemplos dedl()
<?php
// En este ejemplo se carga una extensión u otra dependiendo del sistema operativo
if (!extension_loaded('sqlite')) {
if (strtoupper(substr(PHP_OS,0,3)) ==='WIN') {
dl('php_sqlite.dll');
} else {
dl('sqlite.so');
}
}
// O si la constante PHP_SHLIB_SUFFIX está disponible desde PHP 4.3.0
if (!extension_loaded('sqlite')) {
$prefix= (PHP_SHLIB_SUFFIX==='dll') ?'php_':'';
dl($prefix.'sqlite.'.PHP_SHLIB_SUFFIX);
}
?>| Versión | Descripción |
|---|---|
| 7.0.0 | dl()está deshabilitado en PHP-FPM. |
| 5.3.9 | dl()está deshabilitado en PHP-FPM, aunque se desaconseja. |
| 5.3.0 | dl()está desactivado en algunos módulos SAPI por problemas de estabilidad. Los únicos modulos SAPI que permitendl()son: CLI, CGI and Embed. En su lugar usar las directivasDirectivas de carga de extensiones |
Nota:
dl()nose soporta cuando PHP es compilado con soporte ZTS. Use en su lugarDirectivas de carga de extensionesinstead.
Nota:
dl()es sensible a mayúsculas en sistemas Unix.
(PHP 4, PHP 5, PHP 7, PHP 8)
extension_loaded—Encontrar si una extensión está cargada
$name):boolEncuentra si la extensión está cargada.
nameEl nombre de la extensión. Este parámetro considera el uso de mayúsculas/minúsculas.
Es posible ver los nombres de varias extensiones usandophpinfo(), o si usted usa la versiónCGIoCLIde PHP, puede usar la bandera-mpara listar todas las extensiones disponibles:
$ php -m [PHP Modules] xml tokenizer standard sockets session posix pcre overload mysql mbstring ctype [Zend Modules]
Devuelvetruesi la extensión identificada pornombreestá cargada,falsede lo contrario.
Ejemplo #1 Ejemplo deextension_loaded()
<?php
if (!extension_loaded('gd')) {
if (!dl('gd.so')) {
exit;
}
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8)
gc_collect_cycles—Fuerza la recolección de los ciclos de basura existentes
Recogida de las fuerzas de los ciclos de basura existentes.
Esta función no tiene parámetros.
Devuelve el número de ciclos de recogida.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
gc_disable—Desactiva el recolector de referencia circular
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
gc_enable—Activa el colector de referencia circular
Activa el colector de referencia circular, estableciendozend.enable_gca1.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
gc_enabled—Devuelve el estado del colector de referencia circular
Devuelve el estado del colector de referencia circular.
Esta función no tiene parámetros.
Devuelvetruesi el recolector de basura está activado,falseen caso contrario.
Ejemplo #1 Ejemplo degc_enabled()
<?php
if(gc_enabled())gc_collect_cycles();
?>(PHP 7, PHP 8)
gc_mem_caches—Reclaims memory used by the Zend Engine memory manager
Reclaims memory used by the Zend Engine memory manager.
Esta función no tiene parámetros.
Returns the number of bytes freed.
(PHP 7 >= 7.3.0, PHP 8)
gc_status—Gets information about the garbage collector
Gets information about the current state of the garbage collector.
Esta función no tiene parámetros.
Returns an associative array with the following elements:
"runs""collected""threshold""roots"Ejemplo #1gc_status()Usage
<?php
// create object tree that needs gc collection
$a= newstdClass();
$a->b= [];
for ($i=0;$i<100000;$i++) {
$b= newstdClass();
$b->a=$a;
$a->b[] =$b;
}
unset($a);
unset($b);
gc_collect_cycles();
var_dump(gc_status());El resultado del ejemplo sería algo similar a:
array(4) {
["runs"]=>
int(5)
["collected"]=>
int(100002)
["threshold"]=>
int(50001)
["roots"]=>
int(0)
}
(PHP 4, PHP 5, PHP 7, PHP 8)
get_cfg_var—Obtiene el valor de una opción de configuración de PHP
Obtiene el valor de una opción de configuración de PHP.
Esta función no retornará información de configuración establecida cuando PHP fue compilado, o lee un fichero de configuración de Apache.
Para comprobar si el sistema está usando unfichero de configuración, intente recuperar el valor de la opción de configuración cfg_file_path. Si está disponible, un fichero de configuración está siendo utilizado.
optionEl nombre de la opción de configuración.
Devuelve el valor actual de la variable de configuración de PHP especificada poroption, ofalsesi se produce un error.
| Versión | Descripción |
|---|---|
| 5.3.0 | get_cfg_var()se fijó para ser capaz de retornar un "array" con las opciones ini. |
(PHP 4, PHP 5, PHP 7, PHP 8)
get_current_user—Obtiene el nombre del propietario del script PHP actual
Devuelve el nombre del propietario del script PHP actual.
Devuelve el nombre de usuario como un string.
Ejemplo #1get_current_user()ejemplo
<?php
echo'Propietario script actual: '.get_current_user();
?>El resultado del ejemplo sería algo similar a:
Propietario script actual: SYSTEM
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
get_defined_constants—Devuelve un array asociativo con los nombres de todas las constantes y sus valores
$categorize=false):arrayDevuelve los nombres y valores de todas las constantes definidas actualmente. Esto incluye las creadas por las extensiones, así como las creadas con la funcióndefine().
categorizeProvoca que la función retorne un array multi-dimensional con categorias en las claves de la primera dimensión y constantes y sus valores en la segunda dimensión.
<?php
define("MI_CONSTANTE",1);
print_r(get_defined_constants(true));
?>El resultado del ejemplo sería algo similar a:
Array
(
[Core] => Array
(
[E_ERROR] => 1
[E_WARNING] => 2
[E_PARSE] => 4
[E_NOTICE] => 8
[E_CORE_ERROR] => 16
[E_CORE_WARNING] => 32
[E_COMPILE_ERROR] => 64
[E_COMPILE_WARNING] => 128
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[TRUE] => 1
)
[pcre] => Array
(
[PREG_PATTERN_ORDER] => 1
[PREG_SET_ORDER] => 2
[PREG_OFFSET_CAPTURE] => 256
[PREG_SPLIT_NO_EMPTY] => 1
[PREG_SPLIT_DELIM_CAPTURE] => 2
[PREG_SPLIT_OFFSET_CAPTURE] => 4
[PREG_GREP_INVERT] => 1
)
[user] => Array
(
[MI_CONSTANTE] => 1
)
)
Devuelve un array de arrays nombre_constante => valor_constante, opcionalmente agrupados por nombre de extensión registrando la constante.
| Versión | Descripción |
|---|---|
| 5.3.1 | Sólo para Windows: las constantes fundamentales se clasifican enCore, previamentemhash. |
| 5.3.0 | Constantes fundamentales se clasifican enCore, antesinternal. En Windows, las constantes fundamentales se clasifican enmhash. |
| 5.2.11 | El parámetrocategorizeahora funciona correctamente. Anteriormente, el parámetrocategorizeera interpretado como!is_null($categorize), por lo que cualquier valor distinto denullfuerza a las constantes a ser clasificadas. |
Ejemplo #1 Ejemplo deget_defined_constants()
<?php
print_r(get_defined_constants());
?>El resultado del ejemplo sería algo similar a:
Array
(
[E_ERROR] => 1
[E_WARNING] => 2
[E_PARSE] => 4
[E_NOTICE] => 8
[E_CORE_ERROR] => 16
[E_CORE_WARNING] => 32
[E_COMPILE_ERROR] => 64
[E_COMPILE_WARNING] => 128
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[TRUE] => 1
)
(PHP 4, PHP 5, PHP 7, PHP 8)
get_extension_funcs—Devuelve una matriz con los nombres de funciones de un módulo
$module_name):arrayEsta función devuelve los nombres de todas las funciones definidas en el módulo indicado pornombre_modulo.
module_nameEl nombre del módulo.
Nota:
Este parámetro debe estar enminúsculas.
Devuelve una matriz con todas las funciones, ofalsesinombre_modulono es una extensión válida.
Ejemplo #1 Imprime las funciones XML
<?php
print_r(get_extension_funcs("xml"));
?>El resultado del ejemplo sería algo similar a:
Array
(
[0] => xml_parser_create
[1] => xml_parser_create_ns
[2] => xml_set_object
[3] => xml_set_element_handler
[4] => xml_set_character_data_handler
[5] => xml_set_processing_instruction_handler
[6] => xml_set_default_handler
[7] => xml_set_unparsed_entity_decl_handler
[8] => xml_set_notation_decl_handler
[9] => xml_set_external_entity_ref_handler
[10] => xml_set_start_namespace_decl_handler
[11] => xml_set_end_namespace_decl_handler
[12] => xml_parse
[13] => xml_parse_into_struct
[14] => xml_get_error_code
[15] => xml_error_string
[16] => xml_get_current_line_number
[17] => xml_get_current_column_number
[18] => xml_get_current_byte_index
[19] => xml_parser_free
[20] => xml_parser_set_option
[21] => xml_parser_get_option
[22] => utf8_encode
[23] => utf8_decode
)
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
get_include_path—Obtiene la opción de configuración include_path actual
Obtiene el valor actual de la opción de configuracióninclude_path.
Devuelve la ruta, como una cadena.
Ejemplo #1 Ejemplo deget_include_path()
<?php
echoget_include_path();
// O utilizando ini_get()
echoini_get('include_path');
?>(PHP 4, PHP 5, PHP 7, PHP 8)
get_included_files—Devuelve un array con los nombres de los archivos incluidos o requeridos
Obtiene los nombres de todos los archivos que han sido incluidos usandoinclude,include_once,requireorequire_once.
Devuelve un array con los nombres de los archivos.
El script llamado originalmente es considerado un "archivo incluido", así que será listado junto con los archivos referenciados por la familia de funcionesinclude.
Los archivos que son incluidos o requeridos múltiples veces solo aparecen una vez en el array devuelto.
Ejemplo #1 Ejemplo deget_included_files()
<?php
// Este archivo es abc.php
include'test1.php';
include_once'test2.php';
require'test3.php';
require_once'test4.php';
$archivos_incluidos=get_included_files();
foreach ($archivos_incluidosas$nombre_archivo) {
echo"$nombre_archivo\n";
}
?>El resultado del ejemplo sería:
/path/to/abc.php /path/to/test1.php /path/to/test2.php /path/to/test3.php /path/to/test4.php
(PHP 4, PHP 5, PHP 7, PHP 8)
get_loaded_extensions—Devuelve un array con los nombres de todos los módulos compilados y cargados
$zend_extensions= false):arrayEsta función devuelve los nombres de todos los módulos compilados y cargados en el intérprete de PHP.
zend_extensionsSólo retorna extensiones Zend, si no, las extensiones regulares, como mysqli. El valor predeterminado esfalse(retorna extensiones regulares).
Devuelve un array indexado de todos los nombres de los módulos.
| Versión | Descripción |
|---|---|
| 5.2.4 | Fue añadido el parámetro opcionalzend_extensions |
Ejemplo #1get_loaded_extensions()
<?php
print_r(get_loaded_extensions());
?>El resultado del ejemplo sería algo similar a:
Array ( [0] => xml [1] => wddx [2] => standard [3] => session [4] => posix [5] => pgsql [6] => pcre [7] => gd [8] => ftp [9] => db [10] => calendar [11] => bcmath )
(PHP 4, PHP 5, PHP 7)
get_magic_quotes_gpc—Obtiene el valor actual de configuración de magic_quotes_gpc
Esta función ha sido declaradaOBSOLETAa partir de PHP 7.4.0, y esELIMINADAdesde PHP 8.0.0. Su uso está totalmente desaconsejado.
Siempre retornafalse.
Siempre retornafalse.
| Versión | Descripción |
|---|---|
| 7.4.0 | Esta función ha quedado en desuso. |
(PHP 4, PHP 5, PHP 7)
get_magic_quotes_runtime—Obtiene el valor de configuración activo actual de magic_quotes_runtime
Esta función ha sido declaradaOBSOLETAa partir de PHP 7.4.0. Su uso está totalmente desaconsejado
Devuelve el valor de configuración activo actual demagic_quotes_runtime.
Devuelve 0 si magic_quotes_runtime está off, 1 en caso contrario. O siempre devuelvefalsea partir de PHP 5.4.0.
| Versión | Descripción |
|---|---|
| 7.4.0 | Esta función es obsoleta. |
| 5.4.0 | Siempre devuelvefalsedebido a que la característica de comillas mágicas ha sido eliminada de PHP. |
Ejemplo #1get_magic_quotes_runtime()ejemplo
<?php
// Comprueba si magic_quotes_runtime está activado
if(get_magic_quotes_runtime())
{
// Desactivar
set_magic_quotes_runtime(false);
}
?>Esta función es un alias de:get_included_files().
(PHP 7, PHP 8)
get_resources—Returns active resources
$type=null):arrayReturns an array of all currently activeresources, optionally filtered by resource type.
Nota:This function is meant for debugging and testing purposes. It is not supposed to be used in production environments, especially not to access or even manipulate resources which are normally not accessible (e.g. the underlying stream resource ofSplFileObjectinstances).
typeIf defined, this will causeget_resources()to only return resources of the given type.A list of resource types is available.
If thestringUnknownis provided as the type, then only resources that are of an unknown type will be returned.
If omitted, all resources will be returned.
Returns anarrayof currently active resources, indexed by resource number.
| Versión | Descripción |
|---|---|
| 8.0.0 | typeis nullable now. |
Ejemplo #1 Unfilteredget_resources()
<?php
$fp=tmpfile();
var_dump(get_resources());
?>El resultado del ejemplo sería algo similar a:
array(1) {
[1]=>
resource(1) of type (stream)
}
Ejemplo #2 Filteredget_resources()
<?php
$fp=tmpfile();
var_dump(get_resources('stream'));
var_dump(get_resources('curl'));
?>El resultado del ejemplo sería algo similar a:
array(1) {
[1]=>
resource(1) of type (stream)
}
array(0) {
}
(PHP 4, PHP 5, PHP 7, PHP 8)
getenv—Obtiene el valor de una variable de entorno
$varname):stringObtiene el valor de una variable de entorno.
Se puede ver una lista de todas las variables de entorno usandophpinfo(). Muchas de estas variables están listadas bajo la especificación» RFC 3875, específicamente la sección 4.1, "Request Meta-Variables".
varnameEl nombre de variable.
Devuelve el valor de la variable de entornovarname, ofalsesi la variable entornovarnameno existe.
Ejemplo #1 Ejemplo degetenv()
<?php
// Ejemplo de uso de getenv()
$ip=getenv('REMOTE_ADDR');
// O simplemente use una Superglobal ($_SERVER o $_ENV)
$ip=$_SERVER['REMOTE_ADDR'];
?>(PHP 4, PHP 5, PHP 7, PHP 8)
getlastmod—Obtiene la hora de la última modificación de la página
Obtiene la hora de la última modificación del script principal de la ejecución.
Si está interesado en obtener la hora de la última modificación de un archivo diferente, considere el uso defilemtime().
Devuelve la hora de la última modificación de la página actual. El valor devuelto es una marca de tiempo Unix, apropiada para ser pasada adate(). Devuelvefalseen caso de fallo.
Ejemplo #1 Ejemplo degetlastmod()
<?php
// imprime p.ej. 'Ultima modificación: March 04 1998 20:43:59.'
echo"Ultima modificación: ".date("F d Y H:i:s.",getlastmod());
?>(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
getmygid—Obtener el GID del dueño del script PHP
Obtiene el ID de grupo del script actual.
Devuelve el ID de grupo del script actual, ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
getmyinode—Obtiene el inode del script actual
Obtiene el inode del script actual.
Devuelve el inodo del script actual como un entero, ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
getmypid—Obtiene el ID del proceso PHP
Obtiene el ID del proceso PHP actual.
Devuelve el ID del proceso PHP actual, ofalsesi ocurre un error.
Los IDs de proceso no son únicos, por lo tanto son una fuente débil de entropía. Es recomendable no depender en ids de proceso en contextos sujetos a consideraciones de seguridad.
(PHP 4, PHP 5, PHP 7, PHP 8)
getmyuid—Obtiene el UID del dueño del script PHP
Obtiene el ID de usuario para el script actual.
Devuelve el ID de usuario del script actual, ofalseen caso de error.
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
getopt—Obtiene las opciones de la lista de argumentos de la línea de comandos
$options,array$longopts= ?):arrayAnaliza las opciones pasadas al script.
options-).Por ejemplo, el string de opciones"x"reconocerá la opción-x.Sólo se permiten a-z, A-Z y 0-9.longopts--).Por ejemplo, longopts tuviera un elemento con"opt", reconocería la opción--opt.El parámetrooptionspuede contener los siguientes elementos:
Nota:Los valores opcionales no aceptan un
" "(espacio) como separador.
Nota:
El formato de
optionsy delongoptses casi igual. La única diferencia es quelongoptscontiene un array de opciones (donde cada elemento es la opción) mientras queoptionscontiene un string (donde cada carácter es la opción).
Esta función devolverá un array de parejas opciones / argumentos, ofalseen caso de error.
Nota:
El análisis de opciones finalizará cuando se encuentre alguna no-opción. Todo lo que haya a continuación será descartado.
| Versión | Descripción |
|---|---|
| 5.3.0 | Añadido soporte para usar "=" como separador de argumento/valor. |
| 5.3.0 | Añadido soporte para valores opcionales (especificado mediante "::"). |
| 5.3.0 | El parámetrolongoptsestá disponible en todos los sistemas. |
| 5.3.0 | Esta función ya no depende del sistema y funciona también en Windows. |
Ejemplo #1 Ejemplo degetopt(): Lo básico
<?php
// Script example.php
$options=getopt("f:hp:");
var_dump($options);
?>shell> php example.php -fvalue -h
El resultado del ejemplo sería:
array(2) {
["f"]=>
string(5) "value"
["h"]=>
bool(false)
}
Ejemplo #2 Ejemplo degetopt(): Introducir opciones long
<?php
// Script example.php
$shortopts="";
$shortopts.="f:";// Valor obligatorio
$shortopts.="v::";// Valor opcional
$shortopts.="abc";// Estas opciones no aceptan valores
$longopts= array(
"required:",// Valor obligatorio
"optional::",// Valor opcional
"option",// Sin valores
"opt",// Sin valores
);
$options=getopt($shortopts,$longopts);
var_dump($options);
?>shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option
El resultado del ejemplo sería:
array(6) {
["f"]=>
string(11) "value for f"
["v"]=>
bool(false)
["a"]=>
bool(false)
["required"]=>
string(5) "value"
["optional"]=>
string(14) "optional value"
["option"]=>
bool(false)
}
Ejemplo #3 Ejemplo degetopt(): Pasar varias opciones como una
<?php
// Script example.php
$options=getopt("abc");
var_dump($options);
?>shell> php example.php -aaac
El resultado del ejemplo sería:
array(2) {
["a"]=>
array(3) {
[0]=>
bool(false)
[1]=>
bool(false)
[2]=>
bool(false)
}
["c"]=>
bool(false)
}
(PHP 4, PHP 5, PHP 7, PHP 8)
getrusage—Obtiene el uso de los recursos actuales
$who= 0):arrayEsta es una interfaz degetrusage(2). Obtiene datos devueltos de la llamada al sistema.
whoSi el parámetrowhoes 1, getrusage será llamado conRUSAGE_CHILDREN.
Devuelve un array asociativo que contiene los datos devueltos por la llamada al sistema. Todas las entradas son accesibles mediante el uso de sus nombres de campo documentado.
Ejemplo #1getrusage()ejemplo
<?php
$dat=getrusage();
echo$dat["ru_oublock"];// número de operaciones de salida en bloque
echo$dat["ru_inblock"];// número de operaciones de entrada de bloques
echo$dat["ru_msgsnd"];// número de mensajes de IPC enviados
echo$dat["ru_msgrcv"];// número de mensajes de IPC recibidos
echo$dat["ru_maxrss"];// tamaño máximo de los conjuntos de residentes
echo$dat["ru_ixrss"];// tamaño de memoria integral compartida
echo$dat["ru_idrss"];// tamaño integral de los datos no compartidos
echo$dat["ru_minflt"];// número de reivindicaciones de página (fallos suaves de página)
echo$dat["ru_majflt"];// número de fallos de página (fallos duros de página)
echo$dat["ru_nsignals"];// número de señales recibidas
echo$dat["ru_nvcsw"];// número de cambios de contexto voluntarios
echo$dat["ru_nivcsw"];// número de cambios de contexto involuntarios
echo$dat["ru_nswap"];// número de intercambios
echo$dat["ru_utime.tv_usec"];// tiempo de usuario utilizado (microsegundos)
echo$dat["ru_utime.tv_sec"];// tiempo de usuario utilizado (segundos)
echo$dat["ru_stime.tv_usec"];// tiempo del sistema utilizado (microsegundos)
?>| Versión | Descripción |
|---|---|
| 7.0.0 | Esta función ahora está soportada en Windows |
Nota:
En Windows,getrusage()solamente devolverá los siguientes miembros:
"ru_stime.tv_sec""ru_stime.tv_usec""ru_utime.tv_sec""ru_utime.tv_usec""ru_majflt"(solo siwhoesRUSAGE_SELF)"ru_maxrss"(solo siwhoesRUSAGE_SELF)Si agetrusage()se le llama con
whoestablecido a1(RUSAGE_CHILDREN), se recopilan los usos de recursos para los hilos (lo que significa que la función es llamada internamente conRUSAGE_THREAD).
Nota:
En BeOS 2000, solamente se devuelven los siguientes miembros:
"ru_stime.tv_sec""ru_stime.tv_usec""ru_utime.tv_sec""ru_utime.tv_usec"
Esta función es un alias de:ini_set().
(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)
ini_get_all—Obtiene todas las opciones de configuración
$extension= ?,bool$details= true):arrayDevuelve todas las opciones de configuración registradas.
extensionUn nombre de extensión opcional. Si se establece, la función de retornará únicamente opciones específicas para esa extensión.
detailsRecupera los detalles de configuración o sólo el valor actual de cada configuración. Por omisión estrue(recuperar detalles).
Devuelve un array asociativo con el nombre de la directiva como la clave del array.
Cuando el parámetrodetailsestrue(por omisión) el array contendráglobal_value(establecido enphp.ini),local_value(tal vez establecido conini_set()o.htaccess), yaccess(el nivel de acceso).
Cuando el parámetrodetailsesfalseel valor será el valor actual de la opción.
Vea lasección del manualpara obtener información sobre lo que significan los niveles de acceso.
Nota:
Es posible que una directiva tenga múltiples niveles de acceso, por lo que el
accessmuestra los valores de máscara de bits adecuado.
Nota:
ini_get_all()ignora las opciones ini de "array" como pdo.dsn.*.
| Versión | Descripción |
|---|---|
| 5.3.0 | Se añadiódetails. |
Ejemplo #1ini_get_all()ejemplos
<?php
print_r(ini_get_all("pcre"));
print_r(ini_get_all());
?>El resultado del ejemplo sería algo similar a:
Array
(
[pcre.backtrack_limit] => Array
(
[global_value] => 100000
[local_value] => 100000
[access] => 7
)
[pcre.recursion_limit] => Array
(
[global_value] => 100000
[local_value] => 100000
[access] => 7
)
)
Array
(
[allow_call_time_pass_reference] => Array
(
[global_value] => 0
[local_value] => 0
[access] => 6
)
[allow_url_fopen] => Array
(
[global_value] => 1
[local_value] => 1
[access] => 4
)
...
)
Ejemplo #2 Disablingdetails
<?php
print_r(ini_get_all("pcre",false));// Se añadió en PHP 5.3.0
print_r(ini_get_all(null,false));// Se añadió en PHP 5.3.0
?>El resultado del ejemplo sería algo similar a:
Array
(
[pcre.backtrack_limit] => 100000
[pcre.recursion_limit] => 100000
)
Array
(
[allow_call_time_pass_reference] => 0
[allow_url_fopen] => 1
...
)
(PHP 4, PHP 5, PHP 7, PHP 8)
ini_get—Devuelve el valor de una directiva de configuración
$varname):stringEn caso de éxito devuelve el valor de una directiva de configuración.
varnameNombre de la directiva de configuración.
Devuelve el valor de la opción de configuración como cadena en caso de éxito, o una cadena vacía para valoresnull. Devuelvefalsesi la opción de configuración no existe.
Ejemplo #1 Unos cuantos ejemplos de la funciónini_get()
<?php
/*
Dentro del php.ini tenemos las siguientes directivas junto con sus valores iniciales:
display_errors = On
register_globals = Off
post_max_size = 8M
*/
echo'display_errors = '.ini_get('display_errors') ."\n";
echo'register_globals = '.ini_get('register_globals') ."\n";
echo'post_max_size = '.ini_get('post_max_size') ."\n";
echo'post_max_size+1 = '. (ini_get('post_max_size')+1) ."\n";
echo'post_max_size in bytes = '.return_bytes(ini_get('post_max_size'));
functionreturn_bytes($val) {
$val=trim($val);
$last=strtolower($val[strlen($val)-1]);
switch($last) {
// El modificador 'G' está disponble desde PHP 5.1.0
case'g':
$val*=1024;
case'm':
$val*=1024;
case'k':
$val*=1024;
}
return$val;
}
?>El resultado del ejemplo sería algo similar a:
display_errors = 1 register_globals = 0 post_max_size = 8M post_max_size+1 = 9 post_max_size in bytes = 8388608
Nota:Cuando se consultan valores booleanos
El valor booleano
offserá devuelto como una cadena vacía o "0", mientras que el valor booleanoonserá devuelto será devuelto como "1". Esta función también puede devolver valores iniciales como cadenas.
Nota:Cuando se consultan valores de tamaños de memoria
Muchos valores iniciales de tamaños de memoria, tales comoupload_max_filesize, están almacenados en el ficherophp.inien notación abreviada.ini_get()devolverá la cadena exacta almacenada en el ficherophp.iniyNOsu valor de tipointegerequivalente. Utilizar estos valores en funciones aritméticas puede provocar resultados inesperados. El ejemplo anterior muestra una manera de convertir la notación abreviada a bytes, muy similar a cómo lo hace el código fuente de PHP.
Nota:
ini_get()no puede leer las opciones ini "array" como pdo.dsn.*, devolviendo
falseen este caso.
| Versión | Descripción |
|---|---|
| 5.3.0 | Anteriormente, se devolvía un string si la opción de configuración no existía. Ahora en su lugar se devuelvefalse. |
(PHP 8 >= 8.2.0)
ini_parse_quantity—Get interpreted size from ini shorthand syntax
$shorthand):intReturns the interpreted size in bytes on success from anini shorthand.
shorthandIni shorthand to parse, must be a number followed by an optional multiplier. The following multipliers are supported:k/K(1024),m/M(1048576),g/G(1073741824). The number can be a decimal, hex (prefixed with0xor0X), octal (prefixed with0o,0Oor0) or binary (prefixed with0bor0B)
Returns the interpreted size in bytes as anint.
If the value cannot be parsed, or an invalid multiplier is used, anE_WARNINGis raised.
Ejemplo #1 A fewini_parse_quantity()examples
<?php
var_dump(ini_parse_quantity('1024'));
var_dump(ini_parse_quantity('1024M'));
var_dump(ini_parse_quantity('512K'));
var_dump(ini_parse_quantity('0xFFk'));
var_dump(ini_parse_quantity('0b1010k'));
var_dump(ini_parse_quantity('0o1024'));
var_dump(ini_parse_quantity('01024'));
var_dump(ini_parse_quantity('Foobar'));
var_dump(ini_parse_quantity('10F'));
?>El resultado del ejemplo sería algo similar a:
int(1024) int(1073741824) int(524288) int(261120) int(10240) int(532) int(532) Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility int(0) Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility int(10)
(PHP 4, PHP 5, PHP 7, PHP 8)
ini_restore—Restablece el valor de una opción de configuración
$varname):voidRestaura una opción de configuración dado su valor original.
varnameEl nombre de la opción de configuración.
No devuelve ningún valor.
Ejemplo #1ini_restore()ejemplo
<?php
$setting='y2k_compliance';
echo'Valor actual \''.$setting.'\': '.ini_get($setting),PHP_EOL;
ini_set($setting,ini_get($setting) ?0:1);
echo'Nuevo valor \''.$setting.'\': '.ini_get($setting),PHP_EOL;
ini_restore($setting);
echo'Valor original \''.$setting.'\': '.ini_get($setting),PHP_EOL;
?>El resultado del ejemplo sería:
Valor actual 'y2k_compliance': 1 Nuevo valor 'y2k_compliance': 0 Valor original 'y2k_compliance': 1
(PHP 4, PHP 5, PHP 7, PHP 8)
ini_set—Establece el valor de una directiva de configuración
$varname,string$newvalue):stringEstablece el valor de la directiva de configuración dada. La opción de configuración mantendrá este nuevo valor durante la ejecución del script, y se restaurará cuando acabe el mismo.
varnameNo todas las directivas pueden ser modificadas conini_set(). Hay una lista con todas las directivas disponibles en elapéndice.
newvalueEl nuevo valor para la opción.
Devuelve el valor anterior en caso de éxito,falseen caso de error.
Ejemplo #1 Establece una opción ini
<?php
echoini_get('display_errors');
if (!ini_get('display_errors')) {
ini_set('display_errors','1');
}
echoini_get('display_errors');
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8)
memory_get_peak_usage—Devuelve el máximo de memoria asignada por PHP
$real_usage=false):intDevuelve el máximo de memoria, en bytes, que se ha asignado a su script PHP.
real_usageSi se deja entruepuede obtener el tamaño real de memoria asignada por el sistema. Si no se establece o esfalse, la memoria utilizada poremalloc()es reportada.
Devuelve el máximo de memoria en bytes.
| Versión | Descripción |
|---|---|
| 5.2.1 | Compilar con--enable-memory-limitya no es necesario para que esta función exista. |
| 5.2.0 | Se añadereal_usage. |
(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)
memory_get_usage—Devuelve la cantidad de memoria asignada a PHP
$real_usage=false):intDevuelve la cantidad de memoria, en bytes, que actualmente se asigna a su script PHP.
real_usageEstablecer esto atruepara obtener el tamaño real de memoria asignada por el sistema. Incluyendo las páginas no usadas. Si no se establece o esfalsesolo se informa de la memoria utilizada.
Nota:
PHP no rastrea la memoria que no es asignada por
emalloc()
Devuelve la cantidad de memoria en bytes.
| Versión | Descripción |
|---|---|
| 5.2.1 | Compilar con--enable-memory-limitya no es necesario para que exista esta función. |
| 5.2.0 | Se añadióreal_usage. |
Ejemplo #1 Amemory_get_usage()ejemplo
<?php
// Este es sólo un ejemplo, los siguientes números
// serán diferentes dependiendo de su sistema
echomemory_get_usage() ."\n";// 36640
$a=str_repeat("Hello",4242);
echomemory_get_usage() ."\n";// 57960
unset($a);
echomemory_get_usage() ."\n";// 36744
?>(PHP 8 >= 8.2.0)
memory_reset_peak_usage—Reset the peak memory usage
Resets the peak memory usage returned by thememory_get_peak_usage()function.
Esta función no tiene parámetros.
No devuelve ningún valor.
Ejemplo #1memory_reset_peak_usage()example
<?php
var_dump(memory_get_peak_usage());
$a=str_repeat("Hello",424242);
var_dump(memory_get_peak_usage());
unset($a);
memory_reset_peak_usage();
$a=str_repeat("Hello",2424);
var_dump(memory_get_peak_usage());
?>El resultado del ejemplo sería algo similar a:
int(422440) int(2508672) int(399208)
(PHP 5 >= 5.2.4, PHP 7, PHP 8)
php_ini_loaded_file—Recupera la ruta de acceso al archivo php.ini cargado
Comprueba si un archivophp.inise ha cargado, y recupera su ruta de acceso.
Esta función no tiene parámetros.
La ruta dephp.inicargado, ofalsesi uno no se ha cargado.
Ejemplo #1php_ini_loaded_file()ejemplo
<?php
$inipath=php_ini_loaded_file();
if ($inipath) {
echo'archivo php.ini cargado: '.$inipath;
} else {
echo'ningún archivo php.ini ha sido cargado';
}
?>El resultado del ejemplo sería algo similar a:
Loaded php.ini: /usr/local/php/php.ini
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
php_ini_scanned_files—Devuelve una lista de ficheros .ini procesados del directorio adicional ini
php_ini_scanned_files()devuelve una lista separada por comas de los ficheros de configuración procesados porphp.ini. Los directorios buscados se establecen por una opción de tiempo de compilación y, opcionalmente, por una variable de entorno en tiempo de ejecución: se puede encontrar más información en laguía de instalación.
Los archivos de configuración devueltos incluyen la ruta completa.
Devuelve un string de archivos .ini separados por comas en caso de éxito. Cada coma va seguida por una nueva línea. Si la directiva de configuración--with-config-file-scan-dirno fué establecida y la variable de entornoPHP_INI_SCAN_DIRno es establecida,falsees retornado. Si estaba configurado y el directorio está vacío, un string vacío es retornado. Si un archivo es irreconocible, el archivo todavía se convertirá en el string retornado pero un error de PHP también resultará. Este error de PHP puede ser visto en tiempo de compilación como mientras se usaphp_ini_scanned_files().
Ejemplo #1 Un ejemplo simple para enumerar los archivos ini devueltos
<?php
if ($filelist=php_ini_scanned_files()) {
if (strlen($filelist) >0) {
$files=explode(',',$filelist);
foreach ($filesas$file) {
echo"<li>".trim($file) ."</li>\n";
}
}
}
?>(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
php_sapi_name—Devuelve el tipo de interfaz que hay entre PHP y el servidor
Devuelve una cadena en minúsculas que describe el tipo de interfaz (la API de Servidor, SAPI) que está utilizando PHP. Por ejemplo, en PHP CLI esta cadena será "cli" mientras que en Apache podría tener varios valores diferentes dependiendo de la SAPI que se utilice. Más abajo se enumeran los posibles valores.
Devuelve el tipo de interfaz, como cadena de texto en minúsculas.
Pese a no ser una lista completa, los posibles valores incluyenaolserver,apache,apache2filter,apache2handler,caudium,cgi(hasta PHP 5.3),cgi-fcgi,cli,cli-server,continuity,embed,fpm-fcgi,isapi,litespeed,milter,nsapi,phttpd,pi3web,roxen,thttpd,tux, ywebjames.
Ejemplo #1 Ejemplo dephp_sapi_name()
Este ejemplo comprueba si está la cadenacgi, ya que podría darse un nombre comocgi-fcgi.
<?php
$sapi_type=php_sapi_name();
if (substr($sapi_type,0,3) =='cgi') {
echo"Está usando PHP CGI\n";
} else {
echo"No está usando PHP CGI\n";
}
?>Nota:Una forma alternativa
La constante de PHP
PHP_SAPIcontiene el mismo valor quephp_sapi_name().
Podría no ser evidente cuál es laSAPIen uso, ya que, por ejemplo, en lugar deapachepodría aparecer definida comoapache2handlero comoapache2filter.
(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)
php_uname—Devuelve información sobre el sistema operativo en que se está ejecutando PHP
$mode= "a"):stringphp_uname()devuelve una descripción del sistema operativo en que se está ejecutando PHP. Esta misma información se muestra en la parte superior dephpinfo(). Para obtener solamente el nombre del sistema operativo, considere el uso de la constantePHP_OS, pero tenga en mente que la constante contendrá el sistema operativo en que PHP fuecompilado.
En algunos sistemas más antigos de UNIX, es posible que no se pueda determinar la información del SO actual en cuyo caso se revertirá mostrando el SO en que PHP fue compilado. Esto solo sucederá si la llamada a la libreria uname() no existe o no funciona.
modemodees un caracter simple que define qué información es devuelta:
'a': Elegida por defecto. Contiene todos los modos en la secuencia"s n r v m".'s': Nombre del sistema operativo. ej.FreeBSD.'n': Nombre del Host. ej.localhost.example.com.'r': Nombre de la versión liberada. ej.5.1.2-RELEASE.'v': Información de la versión. Varia mucho entre los sistemas operativos.'m': Tipo de máquina. ej.i386.Devuelve la descripción, como una cadena de texto.
Ejemplo #1 Algúnos ejemplos dephp_uname()
<?php
echophp_uname();
echoPHP_OS;
/* Algúnos posibles resultados:
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux
FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD
Windows NT XN1 5.1 build 2600
WINNT
*/
if (strtoupper(substr(PHP_OS,0,3)) ==='WIN') {
echo'Este un servidor usando Windows!';
} else {
echo'Este es un servidor que no usa Windows!';
}
?>También existen algunasconstantes PHP predefinidasque pueden ser útiles, por ejemplo:
Ejemplo #2 Algunos ejemplos de las constantes relacionadas al SO
<?php
// *nix
echoDIRECTORY_SEPARATOR;// /
echoPHP_SHLIB_SUFFIX;// so
echoPATH_SEPARATOR;// :
// Win*
echoDIRECTORY_SEPARATOR;// \
echoPHP_SHLIB_SUFFIX;// dll
echoPATH_SEPARATOR;// ;
?>(PHP 4, PHP 5, PHP 7, PHP 8)
phpcredits—Imprime los créditos de PHP
$flag= CREDITS_ALL):boolEsta función imprime la lista de créditos de los desarrolladores de PHP, módulos, etc Genera los códigos HTML apropiados para insertar la información en una página.
flagPara generar una página de créditos personalizada, puede utilizar el parámetroflag.
| name | description |
|---|---|
| CREDITS_ALL | Todos los créditos, equivalente a usar:CREDITS_DOCS+CREDITS_GENERAL+CREDITS_GROUP+CREDITS_MODULES+CREDITS_FULLPAGE. Genera una completa e independiente, página HTML con las etiquetas apropiadas. |
| CREDITS_DOCS | Los créditos para el equipo de documentación |
| CREDITS_FULLPAGE | Por lo general se utiliza en combinación con las otras flags. Indica que es independiente de la página HTML debe ser impreso con la información indicada por las otras flags. |
| CREDITS_GENERAL | Créditos generales: Diseño y concepto del lenguaje, autores de PHP y el módulo SAPI. |
| CREDITS_GROUP | Una lista de los desarrolladores del núcleo. |
| CREDITS_MODULES | Una lista de los módulos de extensión para PHP, y sus autores. |
| CREDITS_SAPI | Una lista de los módulos de servidor API para PHP, y sus autores. |
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Imprimir los créditos generales
<?php
phpcredits(CREDITS_GENERAL);
?>Ejemplo #2 Imprimir los desarrolladores principales y el grupo de documentación
<?php
phpcredits(CREDITS_GROUP|CREDITS_DOCS|CREDITS_FULLPAGE);
?>Ejemplo #3 Imprimir todos los créditos
<html>
<head>
<title>Mi página de créditos</title>
</head>
<body>
<?php
// Algún código propio
phpcredits(CREDITS_ALL-CREDITS_FULLPAGE);
// algo más de código
?>
</body>
</html>Nota:
phpcredits()genera texto plano en lugar de HTML al usar el modo CLI.
(PHP 4, PHP 5, PHP 7, PHP 8)
phpinfo—Muestra información sobre la configuración de PHP
$what= INFO_ALL):boolMuestra gran cantidad de información sobre el estado actual de PHP. Incluye información sobre las opciones de compilación y extensiones de PHP, versión de PHP, información del servidor y entorno (si se compiló como módulo), entorno PHP, versión del OS, rutas, valor de las opciones de configuración locales y generales, cabeceras HTTP y licencia de PHP.
Como cada sistema se instala diferentephpinfo()se usa comúnmente para revisaropciones de configuraciónyvariables predefinidasdisponibles en un sistema dado
phpinfo()también es una valiosa herramienta de depuración ya que contiene todos valores EGPCS (Environment, GET, POST, Cookie, Server).
whatEl resultado de salida puede ser personalizado al pasar una o más de las siguientesconstantessumadas juntas bit a bit en el parámetro opcionalwhat. También se pueden combinar las respectivas constantes con el operador bit a bitor.
| Nombre(constante) | Valor | Descripción |
|---|---|---|
| INFO_GENERAL | 1 | La línea de configuración, ubicación dephp.ini, fecha de compilación, servidor Web, sistema y más. |
| INFO_CREDITS | 2 | Créditos de PHP. Ver tambiénphpcredits(). |
| INFO_CONFIGURATION | 4 | Valores Locales y Maestros actuales de las directivas PHP. Ver tambiénini_get(). |
| INFO_MODULES | 8 | Módulos cargados y sus respectivos parámetros Ver tambiénget_loaded_extensions(). |
| INFO_ENVIRONMENT | 16 | Información de las variables de entorno. Tambien disponibles en$_ENV. |
| INFO_VARIABLES | 32 | Muestra todas lasvariables predefinidasde EGPCS (Environment, GET, POST, Cookie, Server). |
| INFO_LICENSE | 64 | Información de Licencia de PHP. Ver también el» FAQ de licencia. |
| INFO_ALL | -1 | Muestra toda la información anterior |
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 5.5.0 | Los GUIDs de logos fueron reemplazados con URIs de datos, por lo que desactivar ahora expose_php no tiene efecto sobre el resutaldo de phpinfo(). Los créditos ahora también han sido embebidos en la salida misma en vez mediante enlaces. |
| 5.2.2 | Se añadió la información del "Fichero de configuración cargado", mientras que anteriormente solo existía "Ruta del fichero de configuración (php.ini). |
Ejemplo #1 Ejemplo dephpinfo()
<?php
// Muestra toda la información, por defecto INFO_ALL
phpinfo();
// Muestra solamente la información de los módulos.
// phpinfo(8) hace exactamente lo mismo.
phpinfo(INFO_MODULES);
?>Nota:
En versiones de PHP anteriores a la 5.5.0, las partes de la información que se muestra están deshabilidadas cuando la opción de configuraciónexpose_phpestá establecida a
off. Esto incluye los logos de PHP y Zend y los créditos.
Nota:
phpinfo()muestra texto plano en lugar de HTML cuando se utiliza en la línea de comandos.
(PHP 4, PHP 5, PHP 7, PHP 8)
phpversion—Obtiene la versión de PHP
$extension= ?):stringDevuelve una cadena que contiene la versión del analizador de PHP en ejecución o extensión.
extensionUn nombre de extensión opcional.
Si el parámetro opcionalextensionha sido especificado,phpversion()devuelve la versión de la extensión, ofalsesi no hay información de versión asociada o la extensión no está habilitada.
Ejemplo #1phpversion()Ejemplo básico
<?php
// Imprime ejemplo 'Versión actual de PHP: 5.3.8'
echo'Versión actual de PHP: '.phpversion();
// Imprime ejemplo '2.0' o nada si la extensión no está habilitada
echophpversion('tidy');
?>Ejemplo #2PHP_VERSION_IDEjemplo y uso
<?php
// PHP_VERSION_ID está disponible a partir de PHP 5.2.7, si nuestra
// versión es inferior a eso, entonces emular
if (!defined('PHP_VERSION_ID')) {
$version=explode('.',PHP_VERSION);
define('PHP_VERSION_ID', ($version[0] *10000+$version[1] *100+$version[2]));
}
// PHP_VERSION_ID se define como un número, donde el mayor número,
// es la versión más reciente de PHP usada. Se define tal como se utiliza la
// expresión anterior.
//
// $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
//
// Ahora, con PHP_VERSION_ID podemos comprobar las características que la versión de
// PHP pueda tener, esto no requiere el uso version_compare () cada vez que compruebe si la
// versión de PHP no es compatible con una característica.
//
// Por ejemplo, aquí podemos definir las constantes PHP_VERSION_ * que
// no están disponibles en las versiones anteriores a 5.2.7
if (PHP_VERSION_ID<50207) {
define('PHP_MAJOR_VERSION',$version[0]);
define('PHP_MINOR_VERSION',$version[1]);
define('PHP_RELEASE_VERSION',$version[2]);
// Y así sucesivamente, ...
}
?>Nota:
Esta información también está disponible en la constante predefinida
PHP_VERSION. Más información de versión está disponible utilizando las constantesPHP_VERSION_*
(PHP 4, PHP 5, PHP 7, PHP 8)
putenv—Establece el valor de una variable de entorno
$assignment):boolAgregasettingal entorno del servidor. La variable de entorno existirá únicamente durante la petición actual. Al final de la petición el entorno es recuperado a su estado original.
asignaciónEl parámetro, como p.ej."FOO=BAR"
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Definición de una variable de entorno
<?php
putenv("UNIQID=$uniqid");
?>(PHP 4 >= 4.3.0, PHP 5, PHP 7)
restore_include_path—Restablece el valor de la opción de configuración include_path
Restablece la opción de configuracióninclude_patha su valor maestro original, tal y como se encuentre definido enphp.ini
No devuelve ningún valor.
Ejemplo #1 Ejemplo derestore_include_path()
<?php
echoget_include_path();// .:/usr/local/lib/php
set_include_path('/inc');
echoget_include_path();// /inc
restore_include_path();
// O utilizando ini_restore()
ini_restore('include_path');
echoget_include_path();// .:/usr/local/lib/php
?>(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
set_include_path—Establece la opción de configuración include_path
$new_include_path):stringEstablece la opción de configuracióninclude_pathdurante la duración del script.
new_include_pathEl nuevo valor parainclude_path
Devuelve el valor antiguo deinclude_pathen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo deset_include_path()
<?php
// Funciona a partir de PHP 4.3.0
set_include_path('/usr/lib/pear');
// Funciona en todas las versiones de PHP
ini_set('include_path','/usr/lib/pear');
?>Ejemplo #2 Añadir a la ruta de inclusión
Haciendo uso de la constantePATH_SEPARATORes posible extender la ruta de inclusión independientemente del sistema operativo.
En este ejemplo agregamos/usr/lib/pearal final del valorinclude_pathactual.
<?php
$ruta='/usr/lib/pear';
set_include_path(get_include_path() .PATH_SEPARATOR.$ruta);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
set_time_limit—Limita el tiempo máximo de ejecución
$seconds):boolEstablece el número de segundos que se permite la ejecución de un script. Si esto se alcanza, el script devuelve un error fatal. El límite predeterminado es de 30 segundos o, si es que existe, el valormax_execution_timedefinido en elphp.ini.
Cuando es llamado,set_time_limit()reinicia el contador de tiempo de espera de cero. En otras palabras, si el tiempo de espera por defecto es de 30 segundos, y 25 segundos en la ejecución del script se hace la llamadaset_time_limit(20), el script se ejecutará durante un total de 45 segundos antes de que se agote el tiempo.
secondsEl tiempo de ejecución máximo, en segundos. Si se pone a cero se impone sin límite de tiempo.
Devuelvetrueen caso de éxito, ofalseen caso de fallo.
Nota:
La funciónset_time_limit()y la directiva de configuraciónmax_execution_timesólo afectan el tiempo de ejecución del script mismo. Todo el tiempo dedicado a la actividad que ocurre fuera de la ejecución del script, como las llamadas al sistema usandosystem(), operaciones de secuencia, consultas a la bases de datos, etc. No se incluyen cuando se determina el tiempo máximo del script en funcionamiento. Esto no es cierto en Windows, donde el tiempo medido es real.
(PHP 5 >= 5.2.1, PHP 7, PHP 8)
sys_get_temp_dir—Devuelve la ruta del directorio para archivos temporales
Devuelve la ruta del directorio donde PHP almacena los archivos temporales por defecto.
Devuelve la ruta del directorio temporal.
Ejemplo #1sys_get_temp_dir()example
<?php
// Crear un fichero en el temporal
// directorio de archivos utilizando sys_get_temp_dir()
$temp_file=tempnam(sys_get_temp_dir(),'Tux');
echo$temp_file;
?>El resultado del ejemplo sería algo similar a:
C:\Windows\Temp\TuxA318.tmp
(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
version_compare—Compara dos números de versiones estandarizados de PHP
version_compare()compara dos string de números de versiones estandarizados de PHP.
Esta función, en primer lugar reemplaza los_,-y+por puntos.y las cadenas de texto de versiones y añade puntos.antes y después de cualquier código no numérico, de manera que '4.3.2RC1' sería '4.3.2.RC.1'. Después, compara cada una de las partes, de izquierda a derecha. Si alguna parte contuviera un texto especial de versión, se manejarían con el siguiente orden:cualquier texto que no se encuentre en esta lista<dev<alpha=a<beta=b<RC=rc<#<pl=p. De esta forma, no solo se pueden comparar versiones con diferentes niveles, como '4.1' y '4.1.2', sino que también se pueden comparar versiones específicas de PHP que contengan el estado de desarrollo en que se encuentran.
version1Primer número de versión.
version2Segundo número de versión.
operatorSi se especifica el tercer argumento opcionaloperator, se prueba para una relación en particular. Los posibles operadores son:<,lt,<=,le,>,gt,>=,ge,==,=,eq,!=,<>,nerespectivamente.
Este parámetro es sensible a mayúsculas, por lo que los valores debes estar en minúsculas.
Por omisión,version_compare()devuelve-1si la primera versión es inferior a la segunda,0si son iguales, y1si la segunda es inferior.
Al usar el argumento opcionaloperator, la función de volverátruesi se cumpliera la relación especificada por el operador, ofalseen caso contrario.
Los siguientes ejemplos usan la constantePHP_VERSION, ya que esta contiene el valor de la versión de PHP con que se está ejecutando el código.
Ejemplo #1 Ejemplos deversion_compare()
<?php
if (version_compare(PHP_VERSION,'6.0.0') >=0) {
echo'Soy al menos la versión 6.0.0 de PHP, mi versión: '.PHP_VERSION."\n";
}
if (version_compare(PHP_VERSION,'5.3.0') >=0) {
echo'Soy al menos la versión 5.3.0 de PHP, mi versión: '.PHP_VERSION."\n";
}
if (version_compare(PHP_VERSION,'5.0.0','>=')) {
echo'Estoy usando la versión 5 de PHP, mi versión: '.PHP_VERSION."\n";
}
if (version_compare(PHP_VERSION,'5.0.0','<')) {
echo'Estoy usando la versión 4 de PHP, mi versión: '.PHP_VERSION."\n";
}
?>Nota:
La constante
PHP_VERSIONalmacena la versión de PHP en uso.
Nota:
Tenga presente que las versiones preeliminares, como por ejemplo 5.3.0-dev, se las considera inferiores a la versión final (como por ejemplo 5.3.0).
Nota:
Las cadenas de versiones especiales como
alphaybetason sensibles a mayúsculas/minúsculas. Las cadenas de versiones desde fuentes arbitrarias que no se adhieren al estándar de PHP podrían necesitar ser convertidas a minúsculas mediantestrtolower()antes de llamar aversion_compare().
(PHP 5, PHP 7, PHP 8)
zend_thread_id—Devuelve un identificador único del thread actual
Esta función devuelve un identificador único del thread actual.
Devuelve thread id en formato integer.
Ejemplo #1 Ejemplo dezend_thread_id()
<?php
$thread_id=zend_thread_id();
echo'El thread id actual es: '.$thread_id;
?>El resultado del ejemplo sería algo similar a:
El thread actual es: 7864
Nota:
Esta función solo está disponible en PHP compilado con soporte ZTS (Zend Thread Safety) y modo debug (
--enable-debug).
(PHP 4, PHP 5, PHP 7, PHP 8)
zend_version—Obtiene la versión del motor Zend actual
Devuelve una cadena que contiene la versión del Motor Zend ejecutándose actualmente.
Devuelve el número de versión del Motor Zend, como una cadena.
Ejemplo #1 Ejemplo dezend_version()
<?php
echo"Versión del motor Zend: ".zend_version();
?>El resultado del ejemplo sería algo similar a:
Versión del motor Zend: 2.2.0
Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality or performance of your code.
phpdbg aims to be a lightweight, powerful, easy to use debugging platform for PHP. It offers the following features:
| Option | Example Argument | Description |
|---|---|---|
| -c | -c/my/php.ini | Set php.ini file to load |
| -d | -dmemory_limit=4G | Set a php.ini directive |
| -n | Disable default php.ini | |
| -q | Suppress welcome banner | |
| -v | Enable oplog output | |
| -b | Disable color | |
| -i | -imy.init | Set .phpdbginit file |
| -I | Ignore default .phpdbginit | |
| -O | -Omy.oplog | Set oplog output file |
| -r | Run execution context | |
| -rr | Run execution context and quit after execution (not respecting breakpoints) | |
| -e | Generate extended information for debugger/profiler | |
| -E | Enable step through eval, careful! | |
| -s | -s=, -s=foo | Read code to execute from stdin with an optional delimiter |
| -S | -Scli | Override SAPI name, careful! |
| -l | -l4000 | Setup remote console ports |
| -a | -a192.168.0.3 | Setup remote console bind address |
| -x | Enable xml output (instead of normal text output) | |
| -p | -p, -p=func, -p* | Output opcodes and quit |
| -h | Print the help overview | |
| -V | Print version number | |
| -- | -- arg1 arg2 | Use to delimit phpdbg arguments and php $argv; append any $argv argument after it |
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| phpdbg.eol | 2 | PHP_INI_ALL | Removed as of PHP 8.1.0 |
| phpdbg.path | 6 | Removed as of PHP 8.1.0 |
He aquí una breve explicación de las directivas de configuración.
phpdbg.eolmixedThe kind of line ending to use for output. For setting the value, one of the string aliases must be used.
| intValue | stringAlias |
|---|---|
0 | CRLF,crlf,DOS,dos |
1 | LF,lf,UNIX,unix |
2 | CR,cr,MAC,mac |
phpdbg.pathstringEstas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
PHPDBG_VERSION(string)PHPDBG_FILE(int)PHPDBG_METHOD(int)PHPDBG_LINENO(int)PHPDBG_FUNC(int)PHPDBG_COLOR_PROMPT(int)PHPDBG_COLOR_NOTICE(int)PHPDBG_COLOR_ERROR(int)(PHP 5 >= 5.6.3, PHP 7, PHP 8)
phpdbg_break_file—Inserts a breakpoint at a line in a file
$file,int$line):voidInsert a breakpoint at the givenlinein the givenfile.
fileThe name of the file.
lineThe line number.
No devuelve ningún valor.
(PHP 5 >= 5.6.3, PHP 7, PHP 8)
phpdbg_break_function—Inserts a breakpoint at entry to a function
$function):voidInsert a breakpoint at the entry to the givenfunction.
functionThe name of the function.
No devuelve ningún valor.
(PHP 5 >= 5.6.3, PHP 7, PHP 8)
phpdbg_break_method—Inserts a breakpoint at entry to a method
$class,string$method):voidInsert a breakpoint at the entry to the givenmethodof the givenclass.
classThe name of the class.
methodThe name of the method.
No devuelve ningún valor.
(PHP 5 >= 5.6.3, PHP 7, PHP 8)
phpdbg_break_next—Inserts a breakpoint at the next opcode
Insert a breakpoint at the next opcode.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.6.0, PHP 7, PHP 8)
phpdbg_clear—Clears all breakpoints
Clear all breakpoints that have been set, either via one of thephpdbg_break_*()functions or interactively in the console.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.6.0, PHP 7, PHP 8)
phpdbg_color—Sets the color of certain elements
$element,string$color):voidSet thecolorof the givenelement.
elementOne of thePHPDBG_COLOR_*constants.
colorThe name of the color. One ofwhite,red,green,yellow,blue,purple,cyanorblack, optionally with either a trailing-boldor-underline, for instance,white-boldorgreen-underline.
No devuelve ningún valor.
(PHP 7, PHP 8)
phpdbg_end_oplog—
$options= []):?arrayEsta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
options(PHP 5 >= 5.6.0, PHP 7, PHP 8)
phpdbg_exec—Attempts to set the execution context
$context):string|boolEsta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
contextIf the execution context was set previously it is returned. If the execution context was not set previouslytrueis returned. If the request to set the context fails,falseis returned, and anE_WARNINGraised.
(PHP 7, PHP 8)
phpdbg_get_executable—
$options= []):arrayEsta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
options(PHP 5 >= 5.6.0, PHP 7, PHP 8)
phpdbg_prompt—Sets the command prompt
$string):voidSet the command prompt to the givenstring.
stringThe string to use as command prompt.
No devuelve ningún valor.
(PHP 7, PHP 8)
phpdbg_start_oplog—
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
No devuelve ningún valor.
La extensión runkit proporciona medios para modificar constantes, funciones definidas por el usuario y clases definidas por el usuario. También proporciona variables superglobales personalizadas y sub-intérpretes que se pueden embeber mediante aislamiento de procesos (sandboxing).
Este paquete está hecho como una característica añadida para reemplazar al paquete» classkit. Cuando se compila con la opción--enable-runkit=classkita ./configure, exportará las definiciones de funciones y constantes compatibles con classkit.
Modificar Constantes, Funciones, Clases y Métodosfunciona con todas las distribuciones de PHP 4 y PHP 5. No se necesitan requisitos especiales.
Las Superglobales Personalizadassólo están disponibles en PHP 4.2.0 o posterior.
El Aislamiento de Procesos (Sandboxing)requiere PHP 5.1.0 o posterior, o PHP 5.0.0 con un parche TSRM especial aplicado. Sin importar qué versión de PHP está en uso se debe compilar con la opción--enable-maintainer-zts. Vea el archivoREADMEen el paquete de runkit para información adicional.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/runkit.
Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| runkit.superglobal | "" | PHP_INI_PERDIR | |
| runkit.internal_override | "0" | PHP_INI_SYSTEM |
He aquí una breve explicación de las directivas de configuración.
runkit.superglobalstringEjemplo #1 Superglobales personalizadas con runkit.superglobal=_FOO,_BAR en php.ini
<?php
functionmostrar_valores() {
echo"Foo es$_FOO\n";
echo"Bar es$_BAR\n";
echo"Baz es$_BAZ\n";
}
$_FOO='foo';
$_BAR='bar';
$_BAZ='baz';
/* Muestra foo y bar, pero no baz */
mostrar_valores();
?>runkit.internal_overridebooleanEsta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
RUNKIT_IMPORT_FUNCTIONS(integer)RUNKIT_IMPORT_CLASS_METHODS(integer)RUNKIT_IMPORT_CLASS_CONSTS(integer)RUNKIT_IMPORT_CLASS_PROPS(integer)RUNKIT_IMPORT_CLASS_STATIC_PROPS(integer)RUNKIT_IMPORT_CLASSES(integer)RUNKIT_IMPORT_CLASS_*.RUNKIT_IMPORT_OVERRIDE(integer)RUNKIT_ACC_PUBLIC(integer)RUNKIT_ACC_PROTECTED(integer)RUNKIT_ACC_PRIVATE(integer)RUNKIT_ACC_STATIC(integer)CLASSKIT_ACC_PUBLIC(integer)CLASSKIT_ACC_PROTECTED(integer)CLASSKIT_ACC_PRIVATE(integer)CLASSKIT_AGGREGATE_OVERRIDE(integer)RUNKIT_VERSION(string)CLASSKIT_VERSION(string)(No version information available, might only be in Git)
runkit_constant_add—Similar a define(), excepto que también permite definir en definiciones de clase
constnameNombre de la constante a declarar. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.
valueValor NULL, Bool, Long, Double, String, o Resource a almacenar en la nueva constante.
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
runkit_constant_redefine—Redefinir una constante ya definida
constnameConstante a redefinir. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.
newvalueEl nuevo valor a asignar a la constante.
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
runkit_constant_remove—Eliminar/Borrar una constante ya definida
$constname):boolconstnameNombre de la constante a eliminar. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
runkit_function_add—Añadir una nueva función, similar acreate_function()
$funcname,string$arglist,string$code):boolfuncnameNombre de la función que va a ser creada
arglistLista de argumentos separados por comas
codeCódigo que compone la función
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Un ejemplo derunkit_function_add()
<?php
runkit_function_add('testme','$a,$b','echo "El valor de a es $a\n"; echo "El valor de b es $b\n";');
testme(1,2);
?>El resultado del ejemplo sería:
El valor de a es 1 El valor de b es 2
(No version information available, might only be in Git)
runkit_function_copy—Copiar una función a un nombre de función nuevo
$funcname,string$targetname):boolfuncnameNombre de la función existente
targetnameNombre de la función donde se va a copiar la definición
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Un ejemplo derunkit_function_copy()
<?php
functionoriginal() {
echo"En una función\n";
}
runkit_function_copy('original','duplicado');
original();
duplicado();
?>El resultado del ejemplo sería:
En una función En una función
(No version information available, might only be in Git)
runkit_function_redefine—Reemplazar una definición de función con una nueva implementación
$funcname,string$arglist,string$code):boolNota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opción
runkit.internal_overrideenphp.inidebe ser habilitada.
funcnameNombre de la función a redefinir
arglistNueva lista de argumentos a ser aceptados por la función
codeNueva implementación de código
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Un ejemplo derunkit_function_redefine()
<?php
functiontestme() {
echo"Implementación Original de Testme\n";
}
testme();
runkit_function_redefine('testme','','echo "Nueva Implementación de Testme\n";');
testme();
?>El resultado del ejemplo sería:
Implementación Original de Testme Nueva Implementación de Testme
(No version information available, might only be in Git)
runkit_function_remove—Eliminar una definición de función
$funcname):boolNota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opción
runkit.internal_overrideenphp.inidebe ser habilitada.
funcnameNombre de la función a ser borrada
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
runkit_function_rename—Cambiar el nombre de una función
$funcname,string$newname):boolNota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opción
runkit.internal_overrideenphp.inidebe ser habilitada.
funcnameNombre actual de la función
newnameNombre nuevo de la función
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
runkit_import—Procesar un archivo PHP importando definiciones de funciones y clases, sobrescribiendo cuando sea apropiado
$filename,int$flags= RUNKIT_IMPORT_CLASS_METHODS):boolSimilar ainclude, sin embargo cualquier código que resida fuera de una función o clase es simplemente ignorado. Además, dependiendo del valor deflags, cualquier función o clase ya existente en el entorno de ejecución actual podría ser sobrescrito automáticamente por sus nuevas definiciones.
filenameEl nombre de archivo desde que se va a importar las definiciones de funciones y clases
flagsOperador OR a nivel de bit de lafamilia de constantesRUNKIT_IMPORT_*.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_import()
<?php
// importar clases completamente
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASSES);
/* importar clases, aunque no importar sus propiedades estáticas
(RUNKIT_IMPORT_CLASS_STATIC_PROPS está disponible desde 1.0.1) */
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASSES& ~RUNKIT_IMPORT_CLASS_STATIC_PROPS);
/* importar solamente las propiedades estáticas de las clases
(RUNKIT_IMPORT_CLASS_STATIC_PROPS está disponible desde 1.0.1) */
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASS_STATIC_PROPS);
?>(No version information available, might only be in Git)
runkit_method_add—Añadir dinámicamente un nuevo método a una clase dada
$classname,$methodname,$args,$code,$flags= RUNKIT_ACC_PUBLICclassnameLa clase donde se va a añadir el método
methodnameEl nombre del método a añadir
argsLista de argumentos delimitados por comas para el recién creado método
codeEl código a ser evaluado cuandomethodnamesea llamado
flagsEl tipo de método a crear, puede serRUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDoRUNKIT_ACC_PRIVATEopcionalmente combinado mediante OR de bits conRUNKIT_ACC_STATIC(desde 1.0.1)
Nota:
Este parámetro sólo se usa a partir de PHP 5, ya que, antes de esta versión, todos los métodos eran públicos.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_method_add()
<?php
classEjemplo{
functionfoo() {
echo"foo!\n";
}
}
// crear un objeto de Ejemplo
$e= newEjemplo();
// Añadir un nuevo método público
runkit_method_add(
'Ejemplo',
'sumar',
'$num1, $num2',
'return $num1 + $num2;',
RUNKIT_ACC_PUBLIC
);
// sumar 12 + 4
echo$e->sumar(12,4);
?>El resultado del ejemplo sería:
16
(No version information available, might only be in Git)
runkit_method_copy—Copia un método de una clase a otra
$dClass,$dMethod,$sClass,$sMethod= ?dClassClase destino del método a copiar
dMethodNombre del método destino
sClassClase fuente del método a copiar
sMethodNombre del método a copiar desde la clase fuente. Si se omite este parámetro, se asume el valor dedMethod.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_method_copy()
<?php
classFoo{
functionejemplo() {
return"foo!\n";
}
}
classBar{
// inicialmete sin métodos
}
// copiar el método ejemplo() desde la clase Foo a la clase Bar, como baz()
runkit_method_copy('Bar','baz','Foo','ejemplo');
// imprimir la función copiada
echoBar::baz();
?>El resultado del ejemplo sería:
foo!
(No version information available, might only be in Git)
runkit_method_redefine—Cambiar dinámicamente el código del método dado
$classname,$methodname,$args,$code,$flags= RUNKIT_ACC_PUBLICNota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).
classnameLa clase en la que se va a redefinir el método
methodnameEl nombre del método a redefinir
argsLista de argumentos delimitados por coma para el método redefinido
codeEl nuevo código a ser evaluado cuandomethodnamesea llamado
flagsEl método redefinido puede serRUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDoRUNKIT_ACC_PRIVATEopcionalmente combinado mediante OR de bits conRUNKIT_ACC_STATIC(desde 1.0.1)
Nota:
Este parámetro sólo se usa a partir de PHP 5, ya que, antes de esta versión, todos los métodos eran públicos.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_method_redefine()
<?php
classEjemplo{
functionfoo() {
return"foo!\n";
}
}
// crear un objeto de Ejemplo
$e= newEjemplo();
// imprimir Ejemplo::foo() (antes de redefinir)
echo"Antes: ".$e->foo();
// Redefinir el método 'foo'
runkit_method_redefine(
'Ejemplo',
'foo',
'',
'return "bar!\n";',
RUNKIT_ACC_PUBLIC
);
// imprimir Ejemplo::foo() (después de redefinir)
echo"Después: ".$e->foo();
?>El resultado del ejemplo sería:
Antes: foo! Después: bar!
(No version information available, might only be in Git)
runkit_method_remove—Eliminar dinámicamente el método dado
$classname,string$methodname):boolNota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).
classnameLa clase en la que se va a eliminar el método
methodnameEl nombre del método a eliminar
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_method_remove()
<?php
classEjemplo{
functionfoo() {
return"foo!\n";
}
functionbar() {
return"bar!\n";
}
}
// Eliminar el método 'foo'
runkit_method_remove(
'Ejemplo',
'foo'
);
echoimplode(' ',get_class_methods('Ejemplo'));
?>El resultado del ejemplo sería:
bar
(No version information available, might only be in Git)
runkit_method_rename—Cambiar dinámicamente el nombre del método dado
$classname,string$methodname,string$newname):boolNota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).
classnameLa clase en la que se renombrará el método
methodnameEl nombre del método a renombrar
newnameEl nombre nuevo a dar al método renombrado
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo derunkit_method_rename()
<?php
classEjemplo{
functionfoo() {
return"foo!\n";
}
}
// Renombrar el método 'foo' a 'bar'
runkit_method_rename(
'Ejemplo',
'foo',
'bar'
);
// salida de la función renombrada
echoEjemplo::bar();
?>El resultado del ejemplo sería:
foo!
(PECL runkit7 >= Unknown)
runkit7_object_id—Return the integer object handle for given object
$obj):intThis function is equivalent tospl_object_id().
This function returns a unique identifier for the object. The object id is unique for the lifetime of the object. Once the object is destroyed, its id may be reused for other objects. This behavior is similar tospl_object_hash().
objAny object.
An integer identifier that is unique for each currently existing object and is always the same for each object.
Nota:
When an object is destroyed, its id may be reused for other objects.
(No version information available, might only be in Git)
runkit_superglobals—Devolver el array indexado numéricamente de las superglobales registradas
Devuelve un array indexado numéricamente de las globales registradas actualmente, esto es, _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES
(PECL runkit7 >= Unknown)
runkit7_zval_inspect—Returns information about the passed in value with data types, reference counts, etc
$value):arrayvalueThe value to return the representation of
The array returned by this function contains the following elements:
addressrefcount(optional)is_ref(optional)typeEjemplo #1runkit7_zval_inspect()example
<?php
$var= newDateTime();
var_dump(runkit7_zval_inspect($var));
$var=1;
var_dump(runkit7_zval_inspect($var));
?>El resultado del ejemplo sería:
array(4) {
["address"]=>
string(14) "0x7f45ab21b1e0"
["refcount"]=>
int(2)
["is_ref"]=>
bool(false)
["type"]=>
int(8)
}
array(2) {
["address"]=>
string(14) "0x7f45ab21b1e0"
["type"]=>
int(4)
}
The uopz - User Operations for Zend - extension exposes Zend Engine functionality normally used at compilation and execution time in order to allow modification of the internal structures that represent PHP code, and for user code to interact with the VM.
uopz supports the following activities:
Nota:
All of the activities supported are compatible with opcache
PECL uopz 6.1.1 is not compatible with Xdebug >= 2.9.4. Later uopz versions are not compatible with Xdebug < 2.9.4.
As of uopz 5.0 PHP 7.0 is required. As of uopz 5.1, PHP 7.1+ is required.
uopz releases are hosted by PECL and the source code by» github, the easiest route to installation is the normal PECL route:» https://pecl.php.net/package/uopz.
Windows users can download prebuilt release binaries from the» PECLwebsite.
As of uopz 5.0.0 the extension must be loaded asextension. Before this version it must be loaded aszend_extension.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| uopz.disable | "0" | PHP_INI_SYSTEM | Available as of uopz 5.0.2 |
| uopz.exit | "0" | PHP_INI_SYSTEM | Available as of uopz 6.0.1 |
| uopz.overloads | "1" | PHP_INI_SYSTEM | Available as of uopz 2.0.2. Removed as of uopz 5.0.0. |
He aquí una breve explicación de las directivas de configuración.
uopz.disableboolIf enabled, uopz should stop having any effect on the engine.
uopz.exitboolWhether to allow the execution of exit opcodes or not. This setting can be overridden during runtime by callinguopz_allow_exit().
uopz.overloadsboolEnables the ability to useuopz_overload().
Nota:When running with OPcache enabled, it may be necessary to disable allOPcache optimizations(
opcache.optimization_level=0).
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
The following opcodes are defined as constants by uopz before 5.0.0:
ZEND_EXIT(int)trueto exit,falseto continueZEND_NEW(int)ZEND_THROW(int)ZEND_FETCH_CLASS(int)ZEND_ADD_TRAIT(int)ZEND_ADD_INTERFACE(int)ZEND_INSTANCEOF(int)The following constants control the VM's behaviour after a user handler is invoked, be extremely careful! These constants are removed as of uopz 5.0.0.
ZEND_USER_OPCODE_CONTINUE(int)ZEND_USER_OPCODE_ENTER(int)ZEND_USER_OPCODE_LEAVE(int)ZEND_USER_OPCODE_DISPATCH(int)ZEND_USER_OPCODE_DISPATCH_TO(int)ZEND_USER_OPCODE_RETURN(int)The following modifiers are registered as constants by uopz
ZEND_ACC_PUBLIC(int)ZEND_ACC_PROTECTED(int)ZEND_ACC_PRIVATE(int)ZEND_ACC_STATIC(int)ZEND_ACC_FINAL(int)ZEND_ACC_ABSTRACT(int)ZEND_ACC_CLASS(int)ZEND_ACC_INTERFACE(int)ZEND_ACC_TRAIT(int)ZEND_ACC_FETCH(int)(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_add_function—Adds non-existent function or method
$class,$function,$handler,&$flags= ZEND_ACC_PUBLIC,&$all=trueAdds a non-existent function or method.
classThe name of the class.
functionThe name of the function or method.
handlerTheClosurethat defines the new function or method.
flagsFlags to set for the new function or method.
allWhether all classes that descend fromclasswill also be affected.
Devuelvetrueen caso de éxito ofalseen caso de error.
uopz_add_function()throws aRuntimeExceptionif the function or method to add already exists.
Ejemplo #1 Basicuopz_add_function()Usage
<?php
uopz_add_function('foo', function () {echo'bar';});
foo();
?>El resultado del ejemplo sería:
bar
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_allow_exit—Allows control over disabled exit opcode
$allow):voidBy default uopz disables the exit opcode, soexit()calls are practically ignored.uopz_allow_exit()allows to control this behavior.
allowWhether to allow the execution of exit opcodes or not.
No devuelve ningún valor.
Ejemplo #1uopz_allow_exit()example
<?php
exit(1);
echo1;
uopz_allow_exit(true);
exit(2);
echo2;
?>El resultado del ejemplo sería:
1
OPcacheoptimizes away dead code after unconditional exit.
(PECL uopz 1 >= 1.0.3, PECL uopz 2)
uopz_backup—Backup a function
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
$function):void$class,string$function):voidBackup a function at runtime, to be restored on shutdown
classThe name of the class containing the function to backup
functionThe name of the function
Ejemplo #1uopz_backup()example
<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
returntrue;
});
var_dump(fgets());
?>El resultado del ejemplo sería:
bool(true)
(PECL uopz 1, PECL uopz 2)
uopz_compose—Compose a class
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
$name,$classes,$methods= ?,$properties= ?,$flags= ?Creates a new class of the given name that implements, extends, or uses all of the provided classes
nameA legal class name
classesAn array of class, interface and trait names
methodsAn associative array of methods, values are either closures or [modifiers => closure]
propertiesAn associative array of properties, keys are names, values are modifiers
flagsEntry type, by default ZEND_ACC_CLASS
Ejemplo #1uopz_compose()example
<?php
classmyClass{}
traitmyTrait{}
interfacemyInterface{}
uopz_compose(
Composed::class, [
myClass::class,
myTrait::class,
myInterface::class
], [
"__construct"=> function() {
/* ... */
}
]);
var_dump(
class_uses(Composed::class),
class_parents(Composed::class),
class_implements(Composed::class));
?>El resultado del ejemplo sería:
array(1) {
["myTrait"]=>
string(7) "myTrait"
}
array(1) {
["myClass"]=>
string(7) "myClass"
}
array(1) {
["myInterface"]=>
string(11) "myInterface"
}
(PECL uopz 1 >= 1.0.4, PECL uopz 2)
uopz_copy—Copy a function
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
Copy a function by name
classThe name of the class containing the function to copy
functionThe name of the function
A Closure for the specified function
Ejemplo #1uopz_copy()example
<?php
$strtotime=uopz_copy('strtotime');
uopz_function("strtotime", function($arg1,$arg2) use($strtotime) {
/* can call original strtotime from here */
var_dump($arg1);
});
var_dump(strtotime('dummy'));
?>El resultado del ejemplo sería:
string(5) "dummy"
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_del_function—Deletes previously added function or method
$function):bool$class,string$function,int&$all=true):boolDeletes a previously added function or method.
classThe name of the class.
functionThe name of the function or method.
allWhether all classes that descend fromclasswill also be affected.
Devuelvetrueen caso de éxito ofalseen caso de error.
uopz_del_function()throws aRuntimeExceptionif the function or method to delete has not been added byuopz_add_function().
Ejemplo #1 Basicuopz_del_function()Usage
<?php
uopz_add_function('foo', function () {echo'bar';});
var_dump(function_exists('foo'));
uopz_del_function('foo');
var_dump(function_exists('foo'));
?>El resultado del ejemplo sería:
bool(true) bool(false)
(PECL uopz 1, PECL uopz 2)
uopz_delete—Delete a function
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
$function):void$class,string$function):voidDeletes a function or method
classfunctionEjemplo #1uopz_delete()example
<?php
uopz_delete("strlen");
echostrlen("Hello World");
?>El resultado del ejemplo sería algo similar a:
PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4
Ejemplo #2uopz_delete()class example
<?php
classMy{
public static functionstrlen($arg) {
returnstrlen($arg);
}
}
uopz_delete(My::class,"strlen");
echoMy::strlen("Hello World");
?>El resultado del ejemplo sería algo similar a:
PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10
(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)
uopz_extend—Extend a class at runtime
$class,string$parent):boolMakesclassextendparent
classThe name of the class to extend
parentThe name of the class to inherit
Devuelvetrueen caso de éxito ofalseen caso de error.
As of PHP 7.4.0,uopz_extends()throws aRuntimeException, ifOPcacheis enabled, and the class entry of eitherclassorparent(if it is a trait) is immutable.
Ejemplo #1uopz_extend()example
<?php
classA{}
classB{}
uopz_extend(A::class,B::class);
var_dump(class_parents(A::class));
?>El resultado del ejemplo sería:
array(1) {
["B"]=>
string(1) "B"
}
(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_flags—Get or set flags on function or class
$function,int$flags= PHP_INT_MAX):int$class,string$function,int$flags= PHP_INT_MAX):intGet or set the flags on a class or function entry at runtime
classThe name of a class
functionThe name of the function. Ifclassis given and an empty string is passed asfunction,uopz_flags()gets or sets the flags of the class entry.
flagsA valid set of ZEND_ACC_ flags. If omitted,uopz_flags()acts as getter.
If setting, returns old flags, else returns flags
As of PHP 7.4.0, if the parameterflagsis passed,uopz_flags()throws aRuntimeException, ifOPcacheis enabled, and the class entry ofclassor the function entry offunctionis immutable.
| Versión | Descripción |
|---|---|
| PECL uopz 5.0.0 | Theflagsparameter is now optional. Formerly,ZEND_ACC_FETCHhad to be passed to useuopz_flags()as getter. |
Ejemplo #1uopz_flags()example
<?php
classTest{
public functionmethod() {
return__CLASS__;
}
}
$flags=uopz_flags("Test","method");
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_STATIC));
var_dump(uopz_flags("Test","method",$flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_STATIC));
?>El resultado del ejemplo sería:
bool(false) bool(false) int(1234567890) bool(true) bool(true)
Ejemplo #2 "Unfinalize" a Class
<?php
final classMyClass
{
}
$flags=uopz_flags(MyClass::class,'');
uopz_flags(MyClass::class,'',$flags& ~ZEND_ACC_FINAL);
var_dump((newReflectionClass(MyClass::class))->isFinal());
?>El resultado del ejemplo sería:
bool(false)
(PECL uopz 1, PECL uopz 2)
uopz_function—Creates a function at runtime
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
Creates a function at runtime
classThe name of the class to receive the new function
functionThe name of the function
handlerThe Closure for the function
modifiersThe modifiers for the function, by default copied or ZEND_ACC_PUBLIC
Ejemplo #1uopz_function()example
<?php
uopz_function("my_strlen", function($arg) {
returnstrlen($arg);
});
echomy_strlen("Hello World");
?>El resultado del ejemplo sería:
11
Ejemplo #2uopz_function()class example
<?php
classMy{}
uopz_function(My::class,"strlen", function($arg) {
returnstrlen($arg);
},ZEND_ACC_STATIC);
echoMy::strlen("Hello World");
?>El resultado del ejemplo sería:
11
(PECL uopz 5, PECL uopz , PECL uopz 7)
uopz_get_exit_status—Retrieve the last set exit status
Retrieves the last set exit status, i.e. the value passed toexit().
Esta función no tiene parámetros.
This function returns the last exit status, ornullifexit()has not been called.
Ejemplo #1uopz_get_exit_status()example
<?php
exit(123);
echouopz_get_exit_status();?>El resultado del ejemplo sería:
123
OPcacheoptimizes away dead code after unconditional exit.
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_get_hook—Gets previously set hook on function or method
Gets the previously set hook on a function or method.
classThe name of the class.
functionThe name of the function or method.
Returns the previously set hook on a function or method, ornullif no hook has been set.
Ejemplo #1 Basicuopz_get_hook()Usage
<?php
functionfoo() {
echo'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
var_dump(uopz_get_hook('foo'));
?>El resultado del ejemplo sería algo similar a:
object(Closure)#2 (0) {
}
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_get_mock—Get the current mock for a class
classThe name of the mocked class.
Either a string containing the name of the mock, or an object, ornullif no mock has been set.
Ejemplo #1uopz_get_mock()example
<?php
classA{
public static functionwho() {
echo"A";
}
}
classmockA{
public static functionwho() {
echo"mockA";
}
}
uopz_set_mock(A::class,mockA::class);
echouopz_get_mock(A::class);
?>El resultado del ejemplo sería:
mockA
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_get_property—Gets value of class or instance property
Gets the value of a static class property, ifclassis given, or the value of an instance property, ifinstanceis given.
classThe name of the class.
instanceThe object instance.
propertyThe name of the property.
Returns the value of the class or instance property, ornullif the property is not defined.
Ejemplo #1 Basicuopz_get_property()Usage
<?php
classFoo{
private static$staticBar=10;
private$bar=100;
}
$foo= newFoo;
var_dump(uopz_get_property('Foo','staticBar'));
var_dump(uopz_get_property($foo,'bar'));
?>El resultado del ejemplo sería algo similar a:
int(10) int(100)
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_get_return—Gets a previous set return value for a function
Gets the return value of thefunctionpreviously set byuopz_set_return().
classThe name of the class containing the function
functionThe name of the function
The return value or Closure previously set.
Ejemplo #1uopz_get_return()example
<?php
uopz_set_return("strlen",42);
echouopz_get_return("strlen");
?>El resultado del ejemplo sería:
42
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_get_static—Gets the static variables from function or method scope
$class,string$function):array$function):arrayGets the static variables from function or method scope.
classThe name of the class.
functionThe name of the function or method.
Returns an associativearrayof variable names mapped to their current values on success, ornullif the function or method does not exist.
Ejemplo #1 Basicuopz_get_static()Usage
<?php
functionfoo() {
static$bar='baz';
}
var_dump(uopz_get_static('foo'));
?>El resultado del ejemplo sería:
array(1) {
["bar"]=>
string(3) "baz"
}
(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)
uopz_implement—Implements an interface at runtime
$class,string$interface):boolMakesclassimplementinterface
classinterfaceDevuelvetrueen caso de éxito ofalseen caso de error.
As of PHP 7.4.0,uopz_implements()throws aRuntimeException, ifOPcacheis enabled, and the class entry ofclassis immutable.
Ejemplo #1uopz_implement()example
<?php
interfacemyInterface{}
classmyClass{}
uopz_implement(myClass::class,myInterface::class);
var_dump(class_implements(myClass::class));
?>El resultado del ejemplo sería:
array(1) {
["myInterface"]=>
string(11) "myInterface"
}
(PECL uopz 1, PECL uopz 2)
uopz_overload—Overload a VM opcode
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
Overloads the specifiedopcodewith the user defined function
opcodeA valid opcode, see constants for details of supported codes
callableEjemplo #1uopz_overload()example
<?php
uopz_overload(ZEND_EXIT, function(){});
exit();
echo"Hello World";
?>El resultado del ejemplo sería:
Hello World
(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_redefine—Redefine a constant
Redefines the givenconstantasvalue
classThe name of the class containing the constant
constantThe name of the constant
valueThe new value for the constant, must be a valid type for a constant variable
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1uopz_redefine()example
<?php
define("MY",100);
uopz_redefine("MY",1000);
echoMY;
?>El resultado del ejemplo sería:
1000
(PECL uopz 1, PECL uopz 2)
uopz_rename—Rename a function at runtime
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
$function,string$rename):void$class,string$function,string$rename):voidRenamesfunctiontorename
Nota:
If both functions exist, this effectively swaps their names
classThe name of the class containing the function
functionThe name of an existing function
renameThe new name for the function
Ejemplo #1uopz_rename()example
<?php
uopz_rename("strlen","original_strlen");
echooriginal_strlen("Hello World");
?>El resultado del ejemplo sería:
11
Ejemplo #2uopz_rename()class example
<?php
classMy{
public functionstrlen($arg) {
returnstrlen($arg);
}
}
uopz_rename(My::class,"strlen","original_strlen");
echoMy::original_strlen("Hello World");
?>El resultado del ejemplo sería:
11
(PECL uopz 1 >= 1.0.3, PECL uopz 2)
uopz_restore—Restore a previously backed up function
Esta función ha sidoELIMINADAen PECL uopz 5.0.0.
$function):void$class,string$function):voidRestore a previously backed up function
classThe name of the class containing the function to restore
functionThe name of the function
Ejemplo #1uopz_restore()example
<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
returntrue;
});
var_dump(fgets());
uopz_restore('fgets');
fgets();
?>El resultado del ejemplo sería algo similar a:
Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_set_hook—Sets hook to execute when entering a function or method
Sets a hook to execute when entering a function or method.
classThe name of the class.
functionThe name of the function or method.
hookA closure to execute when entering the function or method.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Basicuopz_set_hook()Usage
<?php
functionfoo() {
echo'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
foo();
?>El resultado del ejemplo sería:
barfoo
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_set_mock—Use mock instead of class for new objects
Ifmockis a string containing the name of a class then it will be instantiated instead ofclass.mockcan also be an object.
Nota:
Only dynamic access to properties and methods will use the
mockobject. Static access still uses the originalclass. Seeexamplebelow.
classThe name of the class to be mocked.
mockThe mock to use in the form of a string containing the name of the class to use or an object. If a string is passed, it has to be the fully qualified class name. It is recommended to use the::classmagic constant in this case.
No devuelve ningún valor.
| Versión | Descripción |
|---|---|
| uopz 6.0.0 | Mocking static members is no longer supported by this function.uopz_redefine()anduopz_set_return(), orComponerecan be used instead. |
Ejemplo #1uopz_set_mock()example
<?php
classA{
public functionwho() {
echo"A";
}
}
classmockA{
public functionwho() {
echo"mockA";
}
}
uopz_set_mock(A::class,mockA::class);
(newA)->who();
?>El resultado del ejemplo sería:
mockA
Ejemplo #2uopz_set_mock()example
<?php
classA{
public functionwho() {
echo"A";
}
}
uopz_set_mock(A::class, new class {
public functionwho() {
echo"mockA";
}
});
(newA)->who();
?>El resultado del ejemplo sería:
mockA
Ejemplo #3uopz_set_mock()and static members
As of uopz 6.0.0 mocking static members is no longer supported.
<?php
classA{
constCON='A';
public static functionwho() {
echo"A";
}
}
uopz_set_mock(A::class, new class {
constCON='mockA';
public static functionwho() {
echo"mockA";
}
});
echoA::CON,PHP_EOL;
A::who();
?>El resultado del ejemplo sería:
A A
Output of the above example in uopz 5:
mockA mockA
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_set_property—Sets value of existing class or instance property
Sets the value of an existing static class property, ifclassis given, or the value of an instance property (regardless whether the instance property already exists), ifinstanceis given.
classThe name of the class.
instanceThe object instance.
propertyThe name of the property.
valueThe value to assign to the property.
No devuelve ningún valor.
Ejemplo #1 Basicuopz_set_property()Usage
<?php
classFoo{
private static$staticBar;
private$bar;
public static functiontestStaticBar() {
returnself::$staticBar;
}
public functiontestBar() {
return$this->bar;
}
}
$foo= newFoo;
uopz_set_property('Foo','staticBar',10);
uopz_set_property($foo,'bar',100);
var_dump(Foo::testStaticBar());
var_dump($foo->testBar());
?>El resultado del ejemplo sería:
int(10)
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_set_return—Provide a return value for an existing function
Sets the return value of thefunctiontovalue. Ifvalueis a Closure andexecuteis set, the Closure will be executed in place of the original function. It is possible to call the original function from the Closure.
Nota:
This function replacesuopz_rename().
classThe name of the class containing the function
functionThe name of an existing function
valueThe value the function should return. If a Closure is provided and the execute flag is set, the Closure will be executed in place of the original function.
executeIf true, and a Closure was provided as the value, the Closure will be executed in place of the original function.
True if succeeded, false otherwise.
Ejemplo #1uopz_set_return()example
<?php
uopz_set_return("strlen",42);
echostrlen("Banana");
?>El resultado del ejemplo sería:
42
Ejemplo #2uopz_set_return()example
<?php
uopz_set_return("strlen", function($str) { returnstrlen($str) *2; },true);
echostrlen("Banana");
?>El resultado del ejemplo sería:
12
Ejemplo #3uopz_set_return()class example
<?php
classMy{
public static functionstrlen($arg) {
returnstrlen($arg);
}
}
uopz_set_return(My::class,"strlen", function($str) { returnstrlen($str) *2; },true);
echoMy::strlen("Banana");
?>El resultado del ejemplo sería:
12
(PECL uopz 5, PECL uopz , PECL uopz 7)
uopz_set_static—Sets the static variables in function or method scope
$function,array$static):void$class,string$function,array$static):voidSets the static variables in function or method scope.
classThe name of the class.
functionThe name of the function or method.
staticThe associativearrayof variable names mapped to their values.
No devuelve ningún valor.
Ejemplo #1 Basicuopz_set_static()Usage
<?php
functionfoo() {
static$bar='baz';
var_dump($bar);
}
uopz_set_static('foo', ['bar'=>'qux']);
foo();
?>El resultado del ejemplo sería:
string(3) "qux"
(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_undefine—Undefine a constant
$constant):bool$class,string$constant):boolRemoves the constant at runtime
classThe name of the class containingconstant
constantThe name of an existing constant
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1uopz_undefine()example
<?php
define("MY",true);
uopz_undefine("MY");
var_dump(defined("MY"));
?>El resultado del ejemplo sería:
bool(false)
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_unset_hook—Removes previously set hook on function or method
$function):bool$class,string$function):boolRemoves the previously set hook on a function or method.
classThe name of the class.
functionThe name of the function or method.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Basicuopz_unset_hook()Usage
<?php
functionfoo() {
echo'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
foo();
echoPHP_EOL;
uopz_unset_hook('foo');
foo();
?>El resultado del ejemplo sería:
barfoo foo
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_unset_mock—Unset previously set mock
$class):voidUnsets the previously set mock forclass.
classThe name of the mocked class.
No devuelve ningún valor.
ARuntimeExceptionis thrown, if no mock was previously set forclass.
Ejemplo #1uopz_unset_mock()example
<?php
classA{
public static functionwho() {
echo"A";
}
}
classmockA{
public static functionwho() {
echo"mockA";
}
}
uopz_set_mock(A::class,mockA::class);
uopz_unset_mock(A::class);
A::who();
?>El resultado del ejemplo sería:
A
(PECL uopz 5, PECL uopz 6, PECL uopz 7)
uopz_unset_return—Unsets a previously set return value for a function
$function):bool$class,string$function):boolUnsets the return value of thefunctionpreviously set byuopz_set_return().
classThe name of the class containing the function
functionThe name of the function
True on success
Ejemplo #1uopz_unset_return()example
<?php
uopz_set_return("strlen",42);
$len=strlen("Banana");
uopz_unset_return("strlen");
echo$len+strlen("Banana");
?>El resultado del ejemplo sería:
48
La Extensión de Caché de Windows para PHP es un acelerador de PHP utilizado para incrementar la velocidad de las aplicaciones de PHP que se ejecutan sobre Windows y Windows Server. Una vez que la Extensión de Caché de Windows para PHP está habilitada y cargada por el motor de PHP, las aplicaciones de PHP se podrán aprovechar de la funcionalidad sin ninguna modificación en el código.
La Extensión de Caché de Windows para PHP incluye 5 tipos diferentes de cachés. A continuación se describe el propósito de cada tipo de caché y los beneficios que ofrece.
Caché de opcodes de PHP- PHP es un motor de procesamiento de scripts que lee un flujo de datos de entrada que contiene texto, instrucciones de PHP, o ambas, y produce otro flujo de datos, generalmente en formato HTML. Esto significa que, en un servidor web, el motor de PHP lee, analiza, compila y ejecuta un script de PHP cada vez que es solicitado por un cliente web. Las operaciones de lectura, análisis y compilación añaden una carga adicional a la CPU del servidor web y del sistema de ficheros y por tanto afectar al rendimiento global de una aplicación web PHP. La caché de bytecodes (opcodes) de PHP se utiliza para almacenar, en memoria compartida, el script de bytecodes ya compilado de manera que pueda ser re-utilizado por el motor de PHP para ejecuciones posteriores del mismo script.
El soporte para el almacenamiento en caché de opcode fue eliminado enWincache 2.0.0, todos los usuarios que desean tener un opcache debe utilizar la extensiónOPcacheque se incluye en PHP a partir de PHP 5.5.0.
Caché de Fichero- Incluso con la caché de opcodes de PHP activada, en un sistema de ficheros el motor de PHP, debe acceder a los ficheros de script. Cuando los script de PHP son almacenados en un UNC remoto de compartición de ficheros, las operaciones sobre ficheros introducen una considerable sobrecarga de rendimiento. La Extensión de Caché de Windows para PHP incluye una caché de ficheros que es utilizada para almacenar los contenidos de los ficheros de script de PHP en memoria compartida, lo que reduce la cantidad de operaciones en el sistema de ficheros realizado por el motor de PHP.
Caché de Resolución de Rutas de Ficheros- Los script de PHP a menudo incluyen u operan con ficheros mediante el uso de rutas relativas. Cada ruta de fichero debe ser normalizada por el motor de PHP a una ruta de fichero absoluta. Cuando una aplicación de PHP emplea muchos ficheros PHP y accede a ellos mediante rutas relativas, el tener que resolver las rutas puede afectar de manera negativa al rendimiento de la aplicación. La Extensión de Caché de Windows para PHP ofrece una caché de Resolución de Rutas de Ficheros, que se emplea para almacenar los mapeos entre las rutas relativas de ficheros y las absolutas, reduciendo por tanto la cantidad de resoluciones de rutas que el motor de PHP tiene que realizar.
Caché de Usuario (disponible desde la versión 1.1.0)- Los scripts de PHP pueden aprovecharse de la caché de la memoria compartida mediante el uso del API de la caché de usuario. Los objetos PHP y las variables se pueden almacenar en la caché de usuario y ser reutilizadas en posteriores peticiones. Esto se puede emplear para mejorar el rendimiento de los script de PHP y para compartir datos entre múltiples procesos de PHP.
Gestor de Sesión (disponible desde la versión 1.1.0)- El gestor de sesión WinCache se puede emplear para almacenar los datos de la sesión PHP en la memoria compartida. Esto evita operaciones del sistema de ficheros para leer y escribir datos de sesión, lo que mejora el rendimiento cuando se almacenan grandes cantidades de datos en la sesión de PHP.
The extension is currently supported only on the following configurations:
Windows OS:
PHP:
Nota:The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/wincache.
There are two packages for this extension: one package is for PHP versions 5.2.X, and the other package is for PHP 5.3.X. Select the package that is appropriate for the PHP version being used.
To install and enable the extension, follow these steps:
Unpack the package into some temporary location.
Copy thephp_wincache.dllfile into the PHP extensions folder. Typically this folder is called "ext" and it is located in the same folder with all PHP binary files. For example:C:\Program Files\PHP\ext.
Using a text editor, open the php.ini file, which is usually located in the same folder where all PHP binary files are. For example:C:\Program Files\PHP\php.ini.
Add the following line at the end of the php.ini file:extension = php_wincache.dll.
Save and close thephp.inifile.
Recycle the IIS Application Pools for PHP to pick up the configuration changes. To check that the extension has been enabled, create a file calledphpinfo.phpwith a PHP code that callsphpinfofunction.
Save thephpinfo.phpfile in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://localhost/phpinfo.php. Search within the returned web page for a section calledwincache. If the extension is enabled, then thephpinfooutput will list the configuration settings provided by the WinCache.
Nota:Do not forget to removephpinfo.phpfile from the web site's root folder after verifying that extension has been enabled.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
La siguiente tabla enumera y explica los ajustes de configuración proporcionados por la extensión WinCache:
| Nombre | Por defecto | Mínimo | Máximo | Cambiable | Historial de cambios |
|---|---|---|---|---|---|
| wincache.fcenabled | "1" | "0" | "1" | PHP_INI_ALL | Disponible a partir de WinCache 1.0.0 |
| wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.fcachesize | "24" | "5" | "255" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.fcndetect | "1" | "0" | "1" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.1.0 |
| wincache.maxfilesize | "256" | "10" | "2048" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.ocenabled | "1" | "0" | "1" | PHP_INI_ALL | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0 |
| wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0 |
| wincache.ocachesize | "96" | "15" | "255" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0 |
| wincache.filecount | "4096" | "1024" | "16384" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.chkinterval | "30" | "0" | "300" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.ttlmax | "1200" | "0" | "7200" | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.enablecli | 0 | 0 | 1 | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.ignorelist | NULL | NULL | NULL | PHP_INI_ALL | Disponible a partir de WinCache 1.0.0 |
| wincache.namesalt | NULL | NULL | NULL | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.0.0 |
| wincache.ucenabled | 1 | 0 | 1 | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.1.0 |
| wincache.ucachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.1.0 |
| wincache.scachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.1.0 |
| wincache.rerouteini | NULL | NULL | NULL | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.2.0. Eliminada a partir de 1.3.7 |
| wincache.reroute_enabled | 1 | 0 | 1 | PHP_INI_SYSTEM | PHP_INI_PERDIR | Disponible a partir de WinCache 1.3.7 |
| wincache.srwlocks | 1 | 0 | 1 | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.3.6.3. Eliminada a partir de 2.0.0.0 |
| wincache.filemapdir | NULL | NULL | NULL | PHP_INI_SYSTEM | Disponible a partir de WinCache 1.3.7.4 |
He aquí una breve explicación de las directivas de configuración.
wincache.fcenabledbooleanwincache.fcenabledfilterstringwincache.fcenabled: siwincache.fcenabledse establece a 1, los sitios enumerados enwincache.fcenabledfiltertendrán la caché de ficheros desactivada; siwincache.fcenabledse establece a 0, los sitios enumerados enwincache.fcenabledfiltertendrán la caché activada.wincache.fcachesizeintegerwincache.fcndetectbooleanwincache.chkinterval.wincache.maxfilesizeintegerwincache.ocenabledbooleanwincache.ocenabledfilterstringwincache.ocenabled: siwincache.ocenabledse establece a 1, los sitios enumerados enwincache.ocenabledfiltertendrán la caché de códigos de operaciones desactivada; siwincache.ocenabledse establece a 0, los sitios enumerados enwincache.ocenabledfiltertendrán la caché de códigos de operaciones activada.Esta opción ha sido eliminada a partir de 2.0.0.0wincache.ocachesizeintegerwincache.filecountintegerwincache.chkintervalintegerwincache.ttlmaxintegerwincache.enableclibooleanwincache.ignoreliststringDefine una lista de ficheros que no deberían ser almacenados en caché por la extensión. La lista de ficheros se especifica empleando solamente nombres de ficheros, separados por el símbolo tubería - "|".
Ejemplo #1 Ejemplo dewincache.ignorelist
wincache.ignorelist = "index.php|misc.php|admin.php"
wincache.namesaltstringwincache.ucenabledbooleanwincache.ucachesizeintegerwincache.scachesizeintegerwincache.rerouteinistringwincache.reroute_enabledpara una funcionalidad similar a partir de 1.3.7.wincache.reroute_enabledbooleanwincache.srwlocksbooleanwincache.filemapdirstringThe installation package for WinCache includes a PHP script,wincache.php, that can be used to obtain cache information and statistics.
If the WinCache extension was installed via the Microsoft Web Platform Installer, then this script is located in%SystemDrive%\Program Files\IIS\Windows Cache for PHP\. On a 64-bit version of the Windows Server operating system, the script is located in%SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. If the extension was installed manually, then thewincache.phpwill be located in the same folder from which the content of the installation package was extracted.
To usewincache.php, copy it into a root folder of a Web site or into any subfolder. To protect the script, open it in any text editor and replace the values forUSERNAMEandPASSWORDconstants. If any other IIS authentication is enabled on the server, then follow the instructions in the comments:
Ejemplo #1 Authentication configuration forwincache.php
<?php
/**
* ======================== CONFIGURATION SETTINGS ==============================
* If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
* If you use authentication then replace the default password.
*/
define('USE_AUTHENTICATION',1);
define('USERNAME','wincache');
define('PASSWORD','wincache');
/**
* The Basic PHP authentication will work only when IIS is configured to support
* Anonymous Authentication' and nothing else. If IIS is configured to support/use
* any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
* In that case use the array below to define the names of users in your
* domain/network/workgroup which you want to grant access to.
*/
$user_allowed= array('DOMAIN\user1','DOMAIN\user2','DOMAIN\user3');
/**
* If the array contains string 'all', then all the users authenticated by IIS
* will have access to the page. Uncomment the below line and comment above line
* to grant access to all users who gets authenticated by IIS.
*/
/* $user_allowed = array('all'); */
/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>Nota:Always protect thewincache.phpscript by using either the built-in authentication or the server's authentication mechanism. Leaving this script unprotected may compromise the security of your web application and web server.
The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache. Using shared memory instead of the default file session storage helps improve performance of PHP applications that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures that the session data is not lost during recycling of IIS application pools.
To configure PHP to use WinCache session handler set thephp.inisettingsession.save_handlertowincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file usesession.save_pathdirective.
Ejemplo #1 Enabling WinCache session handler
session.save_handler = wincache session.save_path = C:\inetpub\temp\session\
NOTE:wincache.rerouteiniwas removed as of WinCache 1.3.7.0. It has been replaced with automatic function reroutes. See:wincache.reroute_enabled.
The WinCache functions reroutes (available since WinCache 1.2.0, removed since WinCache 1.3.7.0) can be used to replace built-in PHP functions with their equivalents that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is provided for the following functions:
To configure WinCache to use the functions reroutes use the filereroute.inithat is included in WinCache installation package. Copy this file into the same directory wherephp.inifile is located. After that add the wincache.rerouteini setting inphp.iniand specify an absolute or relative path to thereroute.inifile.
Ejemplo #1 Enabling WinCache functions reroutes
wincache.rerouteini = C:\PHP\reroute.ini
Nota:If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This can be done by usingwincache.fcachesizesetting.
Thereroute.inifile contains the mappings between the native PHP functions and their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:
<PHP function name>:[<number of function parameters>]=<wincache function name>
The example of the file is shown below. In this example the calls to PHP functionfile_get_contents()will be replaced with calls towincache_file_get_contents()only if the number of parameters passed to the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function does not handle all the function's parameters.
Ejemplo #2 Reroute.ini file content
[FunctionRerouteList] file_exists=wincache_file_exists file_get_contents:2=wincache_file_get_contents readfile:2=wincache_readfile is_readable=wincache_is_readable is_writable=wincache_is_writable is_writeable=wincache_is_writable is_file=wincache_is_file is_dir=wincache_is_dir realpath=wincache_realpath filesize=wincache_filesize
Esta extensión no tiene ningún tipo de recurso definido.
Esta extensión no tiene ninguna constante definida.
(PECL wincache >= 1.0.0)
wincache_fcache_fileinfo—Retrieves information about files cached in the file cache
$summaryonly=false):array|falseRetrieves information about file cache content and its usage.
summaryonlyControls whether the returned array will contain information about individual cache entries along with the file cache summary.
Array of meta data about file cache ofalseen caso de error
The array returned by this function contains the following elements:
total_cache_uptime- total time in seconds that the file cache has been activetotal_file_count- total number of files that are currently in the file cachetotal_hit_count- number of times the files have been served from the file cachetotal_miss_count- number of times the files have not been found in the file cachefile_entries- an array that contains the information about all the cached files:
file_name- absolute file name of the cached fileadd_time- time in seconds since the file has been added to the file cacheuse_time- time in seconds since the file has been accessed in the file cachelast_check- time in seconds since the file has been checked for modificationshit_count- number of times the file has been served from the cachefile_size- size of the cached file in bytesEjemplo #1 Awincache_fcache_fileinfo()example
<pre>
<?php
print_r(wincache_fcache_fileinfo());
?>
</pre>El resultado del ejemplo sería:
Array
( [total_cache_uptime] => 3234
[total_file_count] => 5
[total_hit_count] => 0
[total_miss_count] => 1
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 1
[use_time] => 0
[last_check] => 1
[hit_count] => 1
[file_size] => 2435
)
[2] => Array (...iterates for each cached file)
)
)
(PECL wincache >= 1.0.0)
wincache_fcache_meminfo—Recupera información sobre el uso de memoria caché de ficheros
Recupera información sobre el uso de la memoria caché del fichero.
Array de meta datos sobre el uso de memoria caché de ficheros ofalseen caso de error
El array devuelta por esta función contiene los siguientes elementos:
memory_total- cantidad de memoria en bytes asignados para la caché de ficherosmemory_free- cantidad de memoria libre en bytes disponibles para la caché de ficherosnum_used_blks- número de bloques de memoria utilizados por la caché de ficherosnum_free_blks- número de bloques de memoria libre disponibles para la caché de ficherosmemory_overhead- cantidad de memoria en bytes utilizados para las estructuras internas de la caché de ficherosEjemplo #1 Un ejemplo dewincache_fcache_meminfo()
<pre>
<?php
print_r(wincache_fcache_meminfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[memory_total] => 134217728
[memory_free] => 131339120
[num_used_blks] => 361
[num_free_blks] => 3
[memory_overhead] => 5856
)
(PECL wincache >= 1.1.0)
wincache_lock—Obtiene un bloqueo exclusivo en una clave dada
$key,bool$isglobal=false):boolObtiene un bloqueo exclusivo sobre una clave dada. La ejecución del script actual quedará en espera que se pueda obtener el bloqueo. Una vez obtenido el bloqueo, el otro script que intente solicitar dicho bloqueo utilizando la misma clave quedará en espera, hasta que el script actual libere el bloqueo conwincache_unlock().
El uso dewincache_lock()ywincache_unlock()puede causar bloqueos de punto muerto al ejecutar scripts de PHP en un entorno multiproceso como FastCGI. No emplear estas funciones a menos que se esté absolutamente seguro de que son necesarias. Para la mayoría de las operaciones en la caché de usuario no es necesario usar esar estas funciones.
keyNombre de la clave en la cahcé para adquirir el bloqueo.
isglobalControla si el ámbito del bloqueo es a nivel de sistema o local. Los bloqueos locales tienen alcance para la «pool» de la aplicación en el caso de FastCGI de IIS o a todos los procesos de php que tengan el mismo identificador de proceso padre.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Empleo dewincache_lock()
<?php
$fp=fopen("/tmp/lock.txt","r+");
if (wincache_lock(“lock_txt_lock”)) {// realizar un bloqueo exclusivo
ftruncate($fp,0);// truncate file
fwrite($fp,"Write something here\n");
wincache_unlock(“lock_txt_lock”);// liberar el bloqueo
} else {
echo"No se pudo obtener el bloqueo";
}
fclose($fp);
?>(PECL wincache >= 1.0.0)
wincache_ocache_fileinfo—Retrieves information about files cached in the opcode cache
$summaryonly=false):array|falseRetrieves information about opcode cache content and its usage.
Esta función fueELILMINADAen PHP 7.0.0.
summaryonlyControls whether the returned array will contain information about individual cache entries along with the opcode cache summary.
Array of meta data about opcode cache ofalseen caso de error
The array returned by this function contains the following elements:
total_cache_uptime- total time in seconds that the opcode cache has been activetotal_file_count- total number of files that are currently in the opcode cachetotal_hit_count- number of times the compiled opcode have been served from the cachetotal_miss_count- number of times the compiled opcode have not been found in the cacheis_local_cache- true is the cache metadata is for a local cache instance, false if the metadata is for the global cachefile_entries- an array that contains the information about all the cached files:
file_name- absolute file name of the cached fileadd_time- time in seconds since the file has been added to the opcode cacheuse_time- time in seconds since the file has been accessed in the opcode cachelast_check- time in seconds since the file has been checked for modificationshit_count- number of times the file has been served from the cachefunction_count- number of functions in the cached fileclass_count- number of classes in the cached fileEjemplo #1 Awincache_ocache_fileinfo()example
<pre>
<?php
print_r(wincache_ocache_fileinfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
(PECL wincache >= 1.0.0)
wincache_ocache_meminfo—Retrieves information about opcode cache memory usage
Retrieves information about memory usage by opcode cache.
Esta función no tiene parámetros.
Array of meta data about opcode cache memory usage ofalseen caso de error
The array returned by this function contains the following elements:
memory_total- amount of memory in bytes allocated for the opcode cachememory_free- amount of free memory in bytes available for the opcode cachenum_used_blks- number of memory blocks used by the opcode cachenum_free_blks- number of free memory blocks available for the opcode cachememory_overhead- amount of memory in bytes used for the opcode cache internal structuresEsta función fueELILMINADAen PHP 7.0.0.
Ejemplo #1 Awincache_ocache_meminfo()example
<pre>
<?php
print_r(wincache_ocache_meminfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[memory_total] => 134217728
[memory_free] => 112106972
[num_used_blks] => 15469
[num_free_blks] => 4
[memory_overhead] => 247600
)
(PECL wincache >= 1.0.0)
wincache_refresh_if_changed—Refreshes the cache entries for the cached files
$files= NULL):boolRefreshes the cache entries for the files, whose names were passed in the input argument. If no argument is specified then refreshes all the entries in the cache.
filesAn array of file names for files that need to be refreshed. An absolute or relative file paths can be used.
Devuelvetrueen caso de éxito ofalseen caso de error.
WinCache performs regular checks on the cached files to ensure that if any file has changed then the corresponding entry in the cache is updated. By default this check is performed every 30 seconds. If, for example, a PHP script updates another PHP script where the application's configuration settings are stored, then it may happen that after the configuration settings have been saved to a file, the application is still using old settings for some time until the cache is refreshed. In those cases it may be preferrable to refresh the cache right after the file has been changed. The following example shows how this can be done.
Ejemplo #1 Awincache_refresh_if_changed()example
<?php
$filename='C:\inetpub\wwwroot\config.php';
$handle=fopen($filename,'w+');
if ($handle===FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle,'<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>(PECL wincache >= 1.0.0)
wincache_rplist_fileinfo—Retrieves information about resolve file path cache
$summaryonly=false):array|falseRetrieves information about cached mappings between relative file paths and corresponding absolute file paths.
summaryonlyArray of meta data about the resolve file path cache ofalseen caso de error
The array returned by this function contains the following elements:
total_file_count- total number of file path mappings stored in the cacherplist_entries- an array that contains the information about all the cached file paths:
resolve_path- path to a filesubkey_data- corresponding absolute path to a fileEjemplo #1 Awincache_rplist_fileinfo()example
<pre>
<?php
print_r(wincache_rplist_fileinfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[total_file_count] => 5
[rplist_entries] => Array
(
[1] => Array
(
[resolve_path] => checkcache.php
[subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
)
[2] => Array (...iterates for each cached file)
)
)
(PECL wincache >= 1.0.0)
wincache_rplist_meminfo—Retrieves information about memory usage by the resolve file path cache
Retrieves information about memory usage by resolve file path cache.
Esta función no tiene parámetros.
Array of meta data that describes memory usage by resolve file path cache. ofalseen caso de error
The array returned by this function contains the following elements:
memory_total- amount of memory in bytes allocated for the resolve file path cachememory_free- amount of free memory in bytes available for the resolve file path cachenum_used_blks- number of memory blocks used by the resolve file path cachenum_free_blks- number of free memory blocks available for the resolve file path cachememory_overhead- amount of memory in bytes used for the internal structures of resolve file path cacheEjemplo #1 Awincache_rplist_meminfo()example
<pre>
<?php
print_r(wincache_rplist_meminfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[memory_total] => 9437184
[memory_free] => 9416744
[num_used_blks] => 23
[num_free_blks] => 1
[memory_overhead] => 416
)
(PECL wincache >= 1.1.0)
wincache_scache_info—Retrieves information about files cached in the session cache
$summaryonly=false):array|falseRetrieves information about session cache content and its usage.
summaryonlyControls whether the returned array will contain information about individual cache entries along with the session cache summary.
Array of meta data about session cache ofalseen caso de error
The array returned by this function contains the following elements:
total_cache_uptime- total time in seconds that the session cache has been activetotal_item_count- total number of elements that are currently in the session cacheis_local_cache- true is the cache metadata is for a local cache instance, false if the metadata is for the global cachetotal_hit_count- number of times the data has been served from the cachetotal_miss_count- number of times the data has not been found in the cachescache_entries- an array that contains the information about all the cached items:
key_name- name of the key which is used to store the datavalue_type- type of value stored by the keyuse_time- time in seconds since the file has been accessed in the opcode cachelast_check- time in seconds since the file has been checked for modificationsttl_seconds- time remaining for the data to live in the cache, 0 meaning infiniteage_seconds- time elapsed from the time data has been added in the cachehitcount- number of times data has been served from the cacheEjemplo #1 Awincache_scache_info()example
<pre>
<?php
print_r(wincache_scache_info());
?>
</pre>El resultado del ejemplo sería:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[scache_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
(PECL wincache >= 1.1.0)
wincache_scache_meminfo—Recupera información sobre el uso de memoria caché de sesión
Recupera información sobre el uso de memoria caché de la sesión.
Array de metadatos sobre el uso de la memoria caché de sesión ofalseen caso de error
El array devuelto por esta función contiene los siguientes elementos:
memory_total- cantidad de memoria en bytes asignado para la caché de sesiónmemory_free- cantidad de memoria libre en bytes disponible para la caché de sesiónnum_used_blks- número de bloques de memoria utilizados por el caché de la sesiónnum_free_blks- número de bloques disponibles en la memoria de la caché de sesiónmemory_overhead- cantidad de memoria en bytes utilizado para las estructuras de sesión de caché internaEjemplo #1 Ejemplo dewincache_scache_meminfo()
<pre>
<?php
print_r(wincache_scache_meminfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
(PECL wincache >= 1.1.0)
wincache_ucache_add—Adds a variable in user cache only if variable does not already exist in the cache
Adds a variable in user cache, only if this variable doesn't already exist in the cache. The added variable remains in the user cache unless its time to live expires or it is deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.
keyStore the variable using thiskeyname. If a variable with same key is already present the function will fail and returnfalse.keyis case sensitive. To override the value even ifkeyis present usewincache_ucache_set()function instad.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.
valueValue of a variable to store.Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passnullasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See__sleep()for details on serializing objects.
valuesAssociative array of keys and values.
ttlTime for the variable to live in the cache in seconds. After the value specified inttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of0which means the variable will stay in the cache unless explicitly deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.
Ifkeyis string, the function returnstrueon success andfalseon failure.
Ifkeyis an array, the function returns:
false;Ejemplo #1wincache_ucache_add()withkeyas a string
<?php
$bar='BAR';
var_dump(wincache_ucache_add('foo',$bar));
var_dump(wincache_ucache_add('foo',$bar));
var_dump(wincache_ucache_get('foo'));
?>El resultado del ejemplo sería:
bool(true) bool(false) string(3) "BAR"
Ejemplo #2wincache_ucache_add()withkeyas an array
<?php
$colors_array= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>El resultado del ejemplo sería:
array(0) { }
array(4) {
["green"]=> int(-1)
["Blue"]=> int(-1)
["yellow"]=> int(-1)
["cyan"]=> int(-1)
}
string(1) "6"
(PECL wincache >= 1.1.0)
wincache_ucache_cas—Compara la variable con el valor antiguo y le asigna un nuevo valor a este
$key,int$old_value,int$new_value):boolCompara la variable asociada con lakeyconold_valuey si coincide entonces asigna elnew_valuea este.
keyEl parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.
old_valueValor anterior de la variable apuntada porkeyen la memoria caché del usuario. El valor debe ser de tipolong, en caso contrario la función devuelvefalse.
new_valueEl nuevo valor que se asigna a una variable New value which will get assigned to variable indicado por lakeysi se encuentra una coincidencia. El valor debe ser de tipolong, en caso contrario la función devolveráfalse.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Usandowincache_ucache_cas()
<?php
wincache_ucache_set('counter',2922);
var_dump(wincache_ucache_cas('counter',2922,1));
var_dump(wincache_ucache_get('counter'));
?>El resultado del ejemplo sería:
bool(true) int(1)
(PECL wincache >= 1.1.0)
wincache_ucache_clear—Elimina todo el contenido de la caché del usuario
Borra o elimina todos los valores almacenados en la caché del usuario.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Usandowincache_ucache_clear()
<?php
wincache_ucache_set('green',1);
wincache_ucache_set('red',2);
wincache_ucache_set('orange',4);
wincache_ucache_set('blue',8);
wincache_ucache_set('cyan',16);
$array1= array('green','red','orange','blue','cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>El resultado del ejemplo sería:
array(5) { ["green"]=> int(1)
["red"]=> int(2)
["orange"]=> int(4)
["blue"]=> int(8)
["cyan"]=> int(16) }
bool(true)
bool(false)
(PECL wincache >= 1.1.0)
wincache_ucache_dec—Disminuye el valor asociado a la clave
Disminuye el valor asociado a lakeypor 1 o como se especifica pordec_by.
keyEl parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.
dec_byEl valor de la variable asociada por el que conseguirá quekeydisminuya. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con lakeydebe ser de tipolong, en caso contrario la función falla y devolveráfalse.
successSerá establecido atrueen caso de éxito yfalseen caso de error.
Devuelve el valor decrementado en caso de éxito yfalseen caso de error.
Ejemplo #1 Usandowincache_ucache_dec()
<?php
wincache_ucache_set('counter',1);
var_dump(wincache_ucache_dec('counter',2923,$success));
var_dump($success);
?>El resultado del ejemplo sería:
int(2922) bool(true)
(PECL wincache >= 1.1.0)
wincache_ucache_delete—Elimina las variables de la memoria caché del usuario
Elimina los elementos de la caché del usuario apuntado porkey.
keyEl parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.keypuede ser un array de claves.
Devuelvetrueen caso de éxito ofalseen caso de error.
Sikeyes un array, entonces la función devuelvefalsesi cada elemento del array no se borra de la memoria caché del usuario, en caso contrario devuelve un array que consta de todas las claves que se eliminan.
Ejemplo #1 Usandowincache_ucache_delete()conkeycomo un string
<?php
wincache_ucache_set('foo','bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>El resultado del ejemplo sería:
bool(true) bool(false)
Ejemplo #2 Usingwincache_ucache_delete()conkeycomo un array
<?php
$array1= array('green'=>'5','blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('green','blue','yellow','cyan');
var_dump(wincache_ucache_delete($array2));
?>El resultado del ejemplo sería:
array(4) { [0]=> string(5) "green"
[1]=> string(4) "Blue"
[2]=> string(6) "yellow"
[3]=> string(4) "cyan" }
Ejemplo #3 Usingwincache_ucache_delete()conkeycomo un array donde algunos elementos no se pueden eliminar
<?php
$array1= array('green'=>'5','blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('orange','red','yellow','cyan');
var_dump(wincache_ucache_delete($array2));
?>El resultado del ejemplo sería:
array(2) { [0]=> string(6) "yellow"
[1]=> string(4) "cyan" }
(PECL wincache >= 1.1.0)
wincache_ucache_exists—Comprueba si una variable existe en la caché del usuario
$key):boolComprueba si una variable con lakeyexiste en la caché de usuario o no.
keyLakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.
Devuelvetruesi la variable con lakeyexiste, en caso contrario devuelvefalse.
Ejemplo #1 Usandowincache_ucache_exists()
<?php
if (!wincache_ucache_exists('green'))
wincache_ucache_set('green',1);
var_dump(wincache_ucache_exists('green'));
?>El resultado del ejemplo sería:
bool(true)
(PECL wincache >= 1.1.0)
wincache_ucache_get—Obtiene una variable almacenada en la caché del usuario
Obtiene una variable almacenada en la caché del usuario.
keyLakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.keypuede ser un array de claves. En este caso el valor de retorno será un array de valores de cada elemento en el arraykey. Si un objeto, o un array que contiene objetos, es retornado, entonces los objetos serán decodificados. Véase__wakeup()para más detalles sobre decodificar objetos.
successSe establecerá entrueen caso de éxito yfalseen caso de error.
Sikeyes un string, la función devuelve el valor de la variable almacenada con esa clave. El parámetrosuccesses establecido atrueen caso de éxito y afalseen caso de error.
El parámetrokeyes un array, el parámetrosuccesssiempre se establece entrue. El array devuelto (pares nombre => valor) will contendrá sólo aquellos pares nombre => valor en donde la operación de obtención de caché de usuario se ha realizado correctamente. Si ninguna de las claves del array encuentran una coincidencia en la caché del usuario, un array vacío será devuelto.
Ejemplo #1wincache_ucache_get()conkeycomo un string
<?php
wincache_ucache_add('color','blue');
var_dump(wincache_ucache_get('color',$success));
var_dump($success);
?>El resultado del ejemplo sería:
string(4) "blue" bool(true)
Ejemplo #2wincache_ucache_get()conkeycomo un array
<?php
$array1= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('green','Blue','yellow','cyan');
var_dump(wincache_ucache_get($array2,$success));
var_dump($success);
?>El resultado del ejemplo sería:
array(4) { ["green"]=> string(1) "5"
["Blue"]=> string(1) "6"
["yellow"]=> string(1) "7"
["cyan"]=> string(1) "8" }
bool(true)
(PECL wincache >= 1.1.0)
wincache_ucache_inc—Incrementa el valor asociado a la clave
Incrementa el valor asociado a lakeypor 1 o como se especifica porinc_by.
keyLakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.
inc_byEl valor por el cual la variable asociada con lakeyserá incrementada. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con lakeydebe ser de tipolong, de lo contrario la función falla y devuelvefalse.
successSe establecerá entrueen caso de éxito yfalseen caso de error.
Devuelve el valor incrementado en caso de éxito yfalseen caso de error.
Ejemplo #1 Usandowincache_ucache_inc()
<?php
wincache_ucache_set('counter',1);
var_dump(wincache_ucache_inc('counter',2921,$success));
var_dump($success);
?>El resultado del ejemplo sería:
int(2922) bool(true)
(PECL wincache >= 1.1.0)
wincache_ucache_info—Recupera información sobre los datos almacenados en la caché del usuario
$summaryonly=false,string$key= NULL):arrayRecupera información sobre los datos almacenados en la caché del usuario.
summaryonlyControla si el array devuelto contiene información sobre las entradas de caché individuales junto con el resumen caché del usuario.
keyLa clave de una entrada en la caché del usuario. Si se especifica a continuación, el array devuelto contendrá información sólo acerca de que la entrada de caché. Si no se especifica ysummaryonlyes establecido afalseentonces el array devuelto contendrá información sobre todas las entradas en la caché.
Array de metadatos sobre caché de usuario ofalseen caso de error
El array devuelto por esta función contiene los siguientes elementos:
total_cache_uptime- tiempo total en segundos que el caché de usuario ha sido activototal_item_count- número total de elementos que están actualmente en la caché del usuariois_local_cache- true si el caché es de metadatos para una instancia de caché local, false si los metadatos es para el la caché globaltotal_hit_count- número de veces que los datos se han servido de la memoria cachétotal_miss_count- número de veces que los datos no se han encontrado en la cachéucache_entries- un array que contiene la información sobre todos los elementos almacenados en caché:
key_name- nombre de la clave que se utiliza para almacenar los datosvalue_type- tipo de valor almacenado por la claveuse_time- tiempo en segundos desde el fichero ha sido visitado en la caché de código de operaciónlast_check- tiempo en segundos desde el fichero ha sido chequeado para modificacionesis_session- indica si los datos son una variable de sesiónttl_seconds- el tiempo restante de los datos a vivir en la memoria caché, 0 significa infinitoage_seconds- tiempo transcurrido desde el momento que los datos han sido añadidos en la cachéhitcount- número de veces que los datos se han servido de la memoria cachéEjemplo #1 Usarwincache_ucache_info()
<?php
wincache_ucache_get('green');
wincache_ucache_set('green',2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>El resultado del ejemplo sería:
Array
( ["total_cache_uptime"] => int(0)
["is_local_cache"] => bool(false)
["total_item_count"] => int(1)
["total_hit_count"] => int(3)
["total_miss_count"] => int(1)
["ucache_entries"] => Array(1)
( [1] => Array(6)
(
["key_name"] => string(5) "green"
["value_type"] => string(4) "long"
["is_session"] => int(0)
["ttl_seconds"] => int(0)
["age_seconds"] => int(0)
["hitcount"] => int(3)
)
)
)
(PECL wincache >= 1.1.0)
wincache_ucache_meminfo—Recupera información sobre el uso de memoria caché de usuario
Recupera información sobre el uso de memoria caché del usuario.
Array de metadatos sobre el uso de la memoria caché de usuario ofalseen caso de error
El array devuelto por esta función contiene los siguientes elementos:
memory_total- cantidad de memoria en bytes asignado para la caché de usuariomemory_free- cantidad de memoria libre en bytes disponible para la caché de usuarionum_used_blks- número de bloques de memoria utilizados por el caché del usuarionum_free_blks- número de bloques disponibles en la memoria de la caché del usuariomemory_overhead- cantidad de memoria en bytes utilizado para las estructuras de los usuarios de caché internaEjemplo #1 Ejemplo dewincache_ucache_meminfo()
<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>El resultado del ejemplo sería:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
(PECL wincache >= 1.1.0)
wincache_ucache_set—Adds a variable in user cache and overwrites a variable if it already exists in the cache
Adds a variable in user cache. Overwrites a variable if it already exists in the cache. The added or updated variable remains in the user cache unless its time to live expires or it is deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.
keyStore the variable using thiskeyname. If a variable with samekeyis already present the function will overwrite the previous value with the new one.keyis case sensitive.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.
valueValue of a variable to store.Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passnullasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See__sleep()for details on serializing objects.
valuesAssociative array of keys and values.
ttlTime for the variable to live in the cache in seconds. After the value specified inttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of0which means the variable will stay in the cache unless explicitly deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.
Ifkeyis string, the function returnstrueon success andfalseon failure.
Ifkeyis an array, the function returns:
false;Ejemplo #1wincache_ucache_set()withkeyas a string
<?php
$bar='BAR';
var_dump(wincache_ucache_set('foo',$bar));
var_dump(wincache_ucache_get('foo'));
$bar1='BAR1';
var_dump(wincache_ucache_set('foo',$bar1));
var_dump(wincache_ucache_get('foo'));
?>El resultado del ejemplo sería:
bool(true) string(3) "BAR" bool(true) string(3) "BAR1"
Ejemplo #2wincache_ucache_set()withkeyas an array
<?php
$colors_array= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>El resultado del ejemplo sería:
array(0) {}
array(0) {}
string(1) "6"
(PECL wincache >= 1.1.0)
wincache_unlock—Libera un bloqueo exclusivo sobre una clave dada
$key):boolLibera un bloqueo exclusivo que se obtuvo en una clave dada mediantewincache_lock(). Si cualquier otro proceso fue bloqueado en espera de el bloqueo en esta clave, este proceso será capaz de obtener el bloqueo.
Usandowincache_lock()ywincache_unlock()puede causar bloqueos al ejecutar los scripts PHP en un entorno de multi-proceso, como FastCGI. No utilice estas funciones a menos que esté absolutamente seguro de que necesitan para su uso. Para la mayoría de las operaciones en la caché de usuario no es necesario el uso de estas funciones.
keyNombre de la llave en la caché para liberar el bloqueo.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Usarwincache_unlock()
<?php
$fp=fopen("/tmp/lock.txt","r+");
if (wincache_lock(“lock_txt_lock”)) {// hacer un bloqueo exclusivo
ftruncate($fp,0);// truncate file
fwrite($fp,"Escribir algo aquí\n");
wincache_unlock(“lock_txt_lock”);// liberar el bloqueo
} else {
echo"No se pudo obtener el bloqueo!";
}
fclose($fp);
?>Building WinCache extension will require:
For completing first two steps, follow the step-by-step guide for how to» build PHP on Windows.
For getting the WinCache source code follow the instructions described inDownloading PECL extensions.
The following steps describe how to compile and build WinCache on Windows OS:
Open a command prompt which is used to build PHP
Go to the root folder where PHP sources are present
Run the command:
cscript.exe win32\build\buildconf.js
Run the command:
configure.bat --help
--enable-wincache.Run the command:
configure.js [all options used to build PHP] --enable-wincache
--enable-wincacheis the only extra option which is required to ensure that WinCache extension gets built properly. This option will build WinCache and will statically link it with PHP dll. To build WinCache extension as a stand-alone DLL use the option--enable-wincache=shared.Run the command:
nmake
The following steps describe how to verify that WinCache has been built correctly:
Go to the folder where the PHP binaries are built
Run the command:
php.exe -n -d extension=php_wincache.dll -re wincache
El XHProf es un perfilador ligero jerárquico y basado en la instrumentación. Durante la fase de recopilación de datos, lleva un registro de los recuentos de llamadas e incluso métricas para los arcos en el calibre dinámico de un programa. Calcula las exclusivas métricas en la fase de reporte/procesamiento posterior, como el tiempo de espera (transcurrido), El tiempo de la CPU y el uso de la memoria. Un perfil de funciones puede ser dividido por los llamantes o llamadas. El XHProf maneja funciones recursivas detectando ciclos en la caligrafía en el propio momento de la recogida de datos y evitar los ciclos dando nombres calificados de profundidad para las invocaciones recursivas.
XHProf incluye una sencilla interfaz de usuario basada en HTML (escrita en PHP). El navegador basado en La interfaz de usuario para ver los resultados de los perfiles hace que sea fácil ver los resultados o compartirlos. con los compañeros. También se admite una vista de imagen de caligrafía.
Los informes del XHProf a menudo pueden ser útiles para entender la estructura del código siendo ejecutado. La naturaleza jerárquica de los informes puede ser utilizada para determinar, por ejemplo, qué cadena de llamadas llevó a que se llamara a una función en particular.
El XHProf permite comparar dos ejecuciones (también conocidas como informes "diff") o agregar datos de múltiples ejecuciones. Informes diferenciales y agregados, muy parecidos a los informes de una sola ejecución, ofrecen vistas "planas" y "jerárquicas" del perfil.
Se puede encontrar documentación adicional a través del sitio» facebook xhprof.
Aunque no es obligatorio, xhprof incluye una interfaz que está escrito en PHP. Se utiliza para guardar y mostrar los datos reseñados en una forma utilizable, donde la observación se realiza mediante un navegador web. Por lo tanto, un servidor web PHP activado probablemente mejorará la experiencia xhprof.
También hay un "fork" (bifurcación del desarrollo) de la interfaz gráfica de usuario en» http://github.com/preinheimer/xhprof
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/xhprof
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| xhprof.output_dir | "" | PHP_INI_ALL |
He aquí una breve explicación de las directivas de configuración.
xhprof.output_dirstringDirectorio utilizado por la aplicación por defecto de la interfaz iXHProfRuns (es decir, la clase XHProfRuns_Default) para el almacenamiento XHProf.
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
XHPROF_FLAGS_NO_BUILTINS(integer)XHPROF_FLAGS_CPU(integer)XHPROF_FLAGS_MEMORY(integer)Ejemplo #1 Ejemplo Xhprof con interfaz gráfica de usuario opcional
En este ejemplo se inicia y detiene el perfilador, a continuación, utiliza interfaz gráfica de usuario para guardar y analizar los resultados. En otras palabras, el código de la extensión se termina en la llamada axhprof_disable().
<?php
xhprof_enable(XHPROF_FLAGS_CPU+XHPROF_FLAGS_MEMORY);
for ($i=0;$i<=1000;$i++) {
$a=$i*$i;
}
$xhprof_data=xhprof_disable();
$XHPROF_ROOT="/tools/xhprof/";
include_once$XHPROF_ROOT."/xhprof_lib/utils/xhprof_lib.php";
include_once$XHPROF_ROOT."/xhprof_lib/utils/xhprof_runs.php";
$xhprof_runs= newXHProfRuns_Default();
$run_id=$xhprof_runs->save_run($xhprof_data,"xhprof_testing");
echo"http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";
?>El resultado del ejemplo sería algo similar a:
http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing
(PECL xhprof >= 0.9.0)
xhprof_disable—Detiene el perfilador xhprof
Detiene el perfilador, y devuelve los datos xhprof de la ejecución.
Esta función no tiene parámetros.
Unarrayde los datos xhprof, de la ejecución.
Ejemplo #1xhprof_disable()ejemplo
<?php
xhprof_enable();
$foo=strlen("foo bar");
$xhprof_data=xhprof_disable();
print_r($xhprof_data);
?>El resultado del ejemplo sería algo similar a:
Array
(
[main()==>strlen] => Array
(
[ct] => 1
[wt] => 279
)
[main()==>xhprof_disable] => Array
(
[ct] => 1
[wt] => 9
)
[main()] => Array
(
[ct] => 1
[wt] => 610
)
)
(PECL xhprof >= 0.9.0)
xhprof_enable—Inicia perfil xhprof
$flags= 0,array$options= ?):voidInicia perfiles xhprof.
flagsFlags opcionales para añadir información adicional a la creación de perfiles. Véase lasconstantes XHprofPara obtener más información acerca de estos flags, p. ej.,XHPROF_FLAGS_MEMORYpara permitir perfiles de memoria.
optionsUnarrayde opciones opcionales, es decir, la opción 'ignored_functions' para pasar en las funciones que se ignoraron durante el perfilado.
null
| Versión | Descripción |
|---|---|
| 0.9.2 | El parámetro opcionaloptionsfué agregado. |
Ejemplo #1 Ejemplos dexhprof_enable()
<?php
// 1. tiempo transcurrido + memoria + perfiles CPU; e ignorar las funciones integradas (internas)
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS|XHPROF_FLAGS_CPU|XHPROF_FLAGS_MEMORY);
// 2. perfil tiempo transcurrido; ignorando call_user_func* durante el perfilado
xhprof_enable(
0,
array('ignored_functions'=> array('call_user_func',
'call_user_func_array')));
// 3. tiempo transcurrido + perfil de memoria; ignorando call_user_func* durante el perfilado
xhprof_enable(
XHPROF_FLAGS_MEMORY,
array('ignored_functions'=> array('call_user_func',
'call_user_func_array')));
?>(PECL xhprof >= 0.9.0)
xhprof_sample_disable—Detiene la muestra del perfilador xhprof
Detiene la muestra el modo perfilador xhprof, y
Esta función no tiene parámetros.
Unarrayde los datos de muestra xhprof, de la ejecución.
Ejemplo #1 Ejemplo dexhprof_sample_disable()
<?php
xhprof_sample_enable();
for ($i=0;$i<=10000;$i++) {
$a=strlen($i);
$b=$i*$a;
$c=rand();
}
$xhprof_data=xhprof_sample_disable();
print_r($xhprof_data);
?>El resultado del ejemplo sería algo similar a:
Array
(
[1272935300.800000] => main()
[1272935300.900000] => main()
)
(PECL xhprof >= 0.9.0)
xhprof_sample_enable—Iniciar el analisis de XHProf en modo de muestreo
Inicia la creación de perfiles en modo de muestra, que es una versión más ligera de peso dexhprof_enable(). El intervalo de muestreo es 0,1 segundos, y las muestras de registro de la pila de llamadas de función completa. El caso de uso principal es en gastos indirectos más bajos se requiere cuando se hace la supervisión del rendimiento y de diagnóstico.
Esta función no tiene parámetros.
null
Yac (Otro caché), es un caché de datos de usuario de memoria compartida sin bloqueo, podría utilizarse para reemplazar el APC, el memcache local.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/yac.
Los binarios de Windows (ficherosDLL) para esta extensión dePECLestán disponibles en el sitio web de PECL.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| yac.compress_threshold | -1 | PHP_INI_SYSTEM | |
| yac.debug | 0 | PHP_INI_ALL | |
| yac.enable | 1 | PHP_INI_SYSTEM | |
| yac.enable_cli | 0 | PHP_INI_SYSTEM | |
| yac.keys_memory_size | 4M | PHP_INI_SYSTEM | |
| yac.serializer | php | PHP_INI_SYSTEM | |
| yac.values_memory_size | 64M | PHP_INI_SYSTEM |
He aquí una breve explicación de las directivas de configuración.
yac.compress_thresholdintegeryac.debugintegeryac.enableintegeryac.enable_cliintegeryac.keys_memory_sizestringyac.serializerstringyac.values_memory_sizestringEstas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
YAC_VERSION(string)YAC_MAX_KEY_LEN(integer)YAC_MAX_VALUE_RAW_LEN(integer)YAC_MAX_RAW_COMPRESSED_LEN(integer)YAC_SERIALIZER_PHP(integer)YAC_SERIALIZER_JSON(integer)YAC_SERIALIZER_IGBINARY(integer)YAC_SERIALIZER_MSGPACK(integer)YAC_SERIALIZER(string)(PECL yac >= 1.0.0)
(PECL yac >= 1.0.0)
Yac::add—Guardar en caché
$key_vals):boolAñadir un artículo al caché.
keysstringclave
valuevalor mixto, Todo tipo de valor php podría ser almacenado exceptorecurso
ttltiempo de expiración
bool,trueen caso de éxito,falseen caso de fallar.
Nota:
Yac::add()puede fallar si el casillero no se puede obtener, así que, si necesitas que el valor se almacene correctamente, puedes escribir códigos como:
Ejemplo #1 Asegúrate de que el artículo se almacene
while(!$yac->set("key", "vale));
(PECL yac >= 1.0.0)
Yac::__construct—Constructor
$prefix= "")se utiliza un prefijo para preparar las claves, esto podría utilizarse para evitar conflictos entre aplicaciones.
prefixstringprefix
(PECL yac >= 1.0.0)
Yac::delete—Eliminar los artículos de la memoria caché
$keys,int$ttl= ?):boolretira los artículos de la memoria caché
keysclave string, o array de multiples claves para ser removidas.
ttlsi se establece un retraso, la eliminación marcará los elementos como inválidos en ttl segundo.
(PECL yac >= 1.0.0)
Yac::dump—Volcar cache
numEl número máximo de artículos debe ser devuelto
mixed
(PECL yac >= 1.0.0)
Yac::flush—Limpiar el caché
Eliminar todos los valores almacenados
Esta función no tiene parámetros.
bool, siempre true
(PECL yac >= 1.0.0)
Yac::get—Recuperar los valores de caché
keyclavesstring, oarrayde multiples claves.
casSi no esnull, se ajustará al caso del artículo recuperado.
mixed en caso de éxito, false en caso de error
(PECL yac >= 1.0.0)
Yac::__get—Getter
keyclavestring
mixed en caso de éxito,nullen caso de error.
(PECL yac >= 1.0.0)
Yac::info—Estado del caché
Obtener el estado del sistema de caché
Esta función no tiene parámetros.
Devuelve un array, consistente con: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"
(PECL yac >= 1.0.0)
Yac::set—Guardar en el caché
Añade un elemento a la caché, si la clave ya existe, se sobreescribe.
keysclavestring
valuevalor mixed, Todo tipo de valor php podría ser almacenado exceptorecurso
ttltiempo de expiración
el valor de sí mismo
(PECL yac >= 1.0.0)
Yac::__set—Setter
keysclavestring
valuevalor mixed, Todo tipo de valor php podría ser almacenado exceptorecurso
Siempre devuelve el valor de sí mismo
No se requiere de ninguna biblioteca externa para compilar esta extensión.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/openal.
Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Esta extensión define cuatro tipos de recursos:Open AL(Device)- Devuelto poropenal_device_open(),Open AL(Context)- Devuelto poropenal_context_create(),Open AL(Buffer)- Devuelto poropenal_buffer_create(), yOpen AL(Source)- Devuelto poropenal_source_create().
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
ALC_FREQUENCY(integer)ALC_REFRESH(integer)ALC_SYNC(integer)AL_FREQUENCY(integer)AL_BITS(integer)AL_CHANNELS(integer)AL_SIZE(integer)AL_BUFFER(integer)AL_SOURCE_RELATIVE(integer)AL_SOURCE_STATE(integer)AL_PITCH(integer)AL_GAIN(integer)AL_MIN_GAIN(integer)AL_MAX_GAIN(integer)AL_MAX_DISTANCE(integer)AL_ROLLOFF_FACTOR(integer)AL_CONE_OUTER_GAIN(integer)AL_CONE_INNER_ANGLE(integer)AL_CONE_OUTER_ANGLE(integer)AL_REFERENCE_DISTANCE(integer)AL_POSITION(integer)AL_VELOCITY(integer)AL_DIRECTION(integer)AL_ORIENTATION(integer)AL_FORMAT_MONO8(integer)AL_FORMAT_MONO16(integer)AL_FORMAT_STEREO8(integer)AL_FORMAT_STEREO16(integer)AL_INITIAL(integer)AL_PLAYING(integer)AL_PAUSED(integer)AL_STOPPED(integer)AL_LOOPING(integer)AL_TRUE(integer)AL_FALSE(integer)(PECL openal >= 0.1.0)
openal_buffer_create—Genera un buffer OpenAL
Devuelve un recursoOpen AL(Buffer)en éxito ofalseen fallo.
(PECL openal >= 0.1.0)
openal_buffer_data—Carga un buffer con datos
$buffer,$format,$data,$freqbufferUn recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).
formatFormato dedata, uno de:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8yAL_FORMAT_STEREO16
dataBloque de datos de audio binario en elformaty elfreqespecificado.
freqFrecuencia dedatadados en Hz.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_buffer_destroy—Destruye un buffer OpenAL
$buffer):boolbufferUn recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_buffer_get—Recupera una propiedad del buffer OpenAL
$buffer,int$property):intbufferUn recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).
propertyPropiedad especifica, una de:AL_FREQUENCY,AL_BITS,AL_CHANNELSyAL_SIZE.
Devuelve un valor entero apropiada a lapropertyrequerida ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_buffer_loadwav—Carga un archivo .wav dentro de un buffer
$buffer,string$wavfile):boolbufferUn recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).
wavfileRuta al archivo.waven el sistema de archivolocal.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_context_create—Crea un contexto de procesamiento de audio
$device):resourcedeviceUn recursoOpen AL(Device)(previamente creado poropenal_device_open()).
Devuelve un recursoOpen AL(Context)en éxito ofalseen fallo.
(PECL openal >= 0.1.0)
openal_context_current—Crea el corriente contexto especificado
$context):boolcontextUn recursoOpen AL(Context)(previamente creado poropenal_context_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_context_destroy—Destruye un contexto
$context):boolcontextUn recursoOpen AL(Context)(previamente creado poropenal_context_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_context_process—Procesa un contexto especificado
$context):boolcontextUn recursoOpen AL(Context)(previamente creado poropenal_context_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_context_suspend—Suspende el contexto especificado
$context):boolcontextUn recursoOpen AL(Context)(previamente creado poropenal_context_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_device_close—Cierra un dispositivo OpenAL
$device):booldeviceUn recursoOpen AL(Device)(previamente creado poropenal_device_open()) para ser cerrado.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_device_open—Inicia la capa de audio del OpenAL
$device_desc= ?):resourcedevice_descAbre un dispositivo de audio especiado opcionalmente pordevice_desc. Sidevice_descno está especificado el primer dispositivo de audio disponible será usado.
Devuelve un recursoOpen AL(Device)en éxito ofalseen fallo.
(PECL openal >= 0.1.0)
openal_listener_get—Devuelve una propiedad de oyente
propertyPropiedad para recuperar, una de:AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) yAL_ORIENTATION(array(float,float,float)).
Devuelve un flotante o un arreglo de flotantes (como apropiado) ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_listener_set—Establece una propiedad de oyente
propertyPropiedad a establecer, una de:AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) yAL_ORIENTATION(array(float,float,float)).
settingValor a establecer, ya sea flotante, o un arreglo de flotantes como apropiado.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_create—Genera una fuente de recursos
Devuelve un recursoOpen AL(Source)en éxito ofalseen fallo.
(PECL openal >= 0.1.0)
openal_source_destroy—Destruye una fuente de recursos
$source):boolsourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_get—Recupera una propiedad de una fuente del OpenAL
sourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
propertyPropiedad para obtener, una de:AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)).
Devuelve el tipo asociado con la propiedad que se recupera ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_pause—Pausa la fuente
$source):boolsourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_play—Empieza la reproducción de la fuente
$source):boolsourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_rewind—Rebobina la fuente
$source):boolsourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_set—Establece la propiedad de la fuente
sourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
propertyPropiedad para establecer, una de:AL_BUFFER(OpenAL(Source)),AL_LOOPING(bool),AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)).
settingEl valor para asignar a lapropertyespecifica. Consulta la descripción de lapropertypara una descripción de el valor(es) esperando.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_source_stop—Detiene la reproducción de la fuente
$source):boolsourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL openal >= 0.1.0)
openal_stream—Empieza la salida de una fuente
$source,int$format,int$rate):resourcesourceUn recursoOpen AL(Source)(previamente creado poropenal_source_create()).
formatFormato dedata, uno de:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8yAL_FORMAT_STEREO16
rateFrecuencias de datos para las salidas dadas en Hz.
Devuelve un recurso de salida en success ofalseen caso de error.
Este paquete se basa en los libradius de FreeBSD (Autenticación remota telefónica de servicio de usuario). Permite a los clientes realizar la autenticación y la contabilidad por medio de solicitudes de red a servidores remotos.
Esta extensión PECL añade soporte completo para la autenticación Radius (» RFC 2865) y contabilidad Radius (» RFC 2866). Este paquete está disponible para Unix (probado en FreeBSD y Linux) y para Windows.
Nota:
Una descripción exacta de libradius se pueden encontrar» aquí. Una descripción detallada del archivo de configuración se puede encontrar» aquí.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
Esta extensión» PECLno se distribuye con PHP.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/radius.
Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
RADIUS_MPPE_KEY_LEN(int)Several RADIUS functions accept option flags as bitmasks. The constants representing those flags are listed below.
RADIUS_OPTION_SALT(int)When set, this option will result in the attribute value being salt-encrypted.
RADIUS_OPTION_TAGGED(int)When set, this option will result in the attribute value being tagged with the value of the tag parameter.
RADIUS packets, whether requests or responses, always include a type. These constants are provided to make it easier to specify types when usingradius_create_request()and when comparing the result ofradius_send_request().
RADIUS_ACCESS_REQUEST(int)An Access-Request, used to authenticate a user against a RADIUS server. Access request packets must include aRADIUS_NAS_IP_ADDRESSor aRADIUS_NAS_IDENTIFIERattribute, must also include aRADIUS_USER_PASSWORD,RADIUS_CHAP_PASSWORDor aRADIUS_STATEattribute, and should include aRADIUS_USER_NAMEattribute.
RADIUS_ACCESS_ACCEPT(int)An Access-Accept response to an Access-Request indicating that the RADIUS server authenticated the user successfully.
RADIUS_ACCESS_REJECT(int)An Access-Reject response to an Access-Request indicating that the RADIUS server could not authenticate the user.
RADIUS_ACCESS_CHALLENGE(int)An Access-Challenge response to an Access-Request indicating that the RADIUS server requires further information in another Access-Request before authenticating the user.
RADIUS_ACCOUNTING_REQUEST(int)An Accounting-Request, used to convey accounting information for a service to the RADIUS server.
RADIUS_ACCOUNTING_RESPONSE(int)An Accounting-Response response to an Accounting-Request.
RADIUS_COA_REQUEST(int)A CoA-Request, sent from the RADIUS server to indicate that the authorisations within the user session have changed. A response must be sent in the form of a CoA-ACK or a CoA-NAK.
This constant is available in PECL radius 1.3.0 and later.
RADIUS_COA_ACK(int)A CoA-ACK, sent to the RADIUS server to indicate that the user authorisations have been updated.
This constant is available in PECL radius 1.3.0 and later.
RADIUS_COA_NAK(int)A CoA-NAK, sent to the RADIUS server to indicate that the user authorisations could not be updated.
This constant is available in PECL radius 1.3.0 and later.
RADIUS_DISCONNECT_REQUEST(int)A Disconnect-Request, sent from the RADIUS server to indicate that the user session must be terminated.
This constant is available in PECL radius 1.3.0 and later.
RADIUS_DISCONNECT_ACK(int)A Disconnect-ACK, sent to the RADIUS server to indicate that the user session has been terminated.
This constant is available in PECL radius 1.3.0 and later.
RADIUS_DISCONNECT_NAK(int)A Disconnect-NAK, sent to the RADIUS server to indicate that the user session could not be terminated.
This constant is available in PECL radius 1.3.0 and later.
These constants define RADIUS attribute types that can be used withradius_put_addr(),radius_put_attr(),radius_put_int()andradius_put_string().
RADIUS_USER_NAME(int)The User-Name attribute. The attribute value is expected to be astringcontaining the name of the user being authenticated, and can be set usingradius_put_attr().
RADIUS_USER_PASSWORD(int)The User-Password attribute. The attribute value is expected to be astringcontaining the user's password, and can be set usingradius_put_attr(). This value will be obfuscated on transmission as described in» section 5.2 of RFC 2865.
RADIUS_CHAP_PASSWORD(int)The Chap-Password attribute. The attribute value is expected to be astringwith the first byte containing the CHAP identifier, and the subsequent 16 bytes containing the MD5 hash of the CHAP identifier, the plaintext password and the CHAP challenge value concatenated together. Note that the CHAP challenge value should also be sent separately in aRADIUS_CHAP_CHALLENGEattribute.
Ejemplo #1 Using CHAP passwords
<?php
// Firstly, we'll create an authentication handle and request.
$radh=radius_auth_open();
radius_add_server($radh,$server,$port,$secret,3,3);
radius_create_request($radh,RADIUS_ACCESS_REQUEST);
// Assuming $password contains the plaintext password, we now:
// Generate a challenge.
$challenge=mt_rand();
// Specify a CHAP identifier.
$ident=1;
// Add the Chap-Password attribute.
$cp=md5(pack('Ca*',$ident,$password.$challenge),true);
radius_put_attr($radh,RADIUS_CHAP_PASSWORD,pack('C',$ident).$cp);
// Add the Chap-Challenge attribute.
radius_put_attr($radh,RADIUS_CHAP_CHALLENGE,$challenge);
/* From here, you would add the remaining attributes and
* call radius_send_request(). */
?>RADIUS_NAS_IP_ADDRESS(int)The NAS-IP-Address attribute. The attribute value is expected to the IP address of the RADIUS client encoded as anint, which can be set usingradius_put_addr().
RADIUS_NAS_PORT(int)The NAS-Port attribute. The attribute value is expected to be the physical port of the user on the RADIUS client encoded as anint, which can be set usingradius_put_int().
RADIUS_SERVICE_TYPE(int)The Service-Type attribute. The attribute value indicates the service type the user is requesting, and is expected to be anint, which can be set usingradius_put_int().
A number of constants are provided to represent the possible values of this attribute. They include:
RADIUS_LOGINRADIUS_FRAMEDRADIUS_CALLBACK_LOGINRADIUS_CALLBACK_FRAMEDRADIUS_OUTBOUNDRADIUS_ADMINISTRATIVERADIUS_NAS_PROMPTRADIUS_AUTHENTICATE_ONLYRADIUS_CALLBACK_NAS_PROMPTRADIUS_FRAMED_PROTOCOL(int)The Framed-Protocol attribute. The attribute value is expected to be anintindicating the framing to be used for framed access, and can be set usingradius_put_int(). The possible attribute values include these constants:
RADIUS_PPPRADIUS_SLIPRADIUS_ARAPRADIUS_GANDALFRADIUS_XYLOGICSRADIUS_FRAMED_IP_ADDRESS(int)The Framed-IP-Address attribute. The attribute value is expected to be the address of the user's network encoded as anint, which can be set usingradius_put_addr()and retrieved usingradius_cvt_addr().
RADIUS_FRAMED_IP_NETMASK(int)The Framed-IP-Netmask attribute. The attribute value is expected to be the netmask of the user's network encoded as anint, which can be set usingradius_put_addr()and retrieved usingradius_cvt_addr().
RADIUS_FRAMED_ROUTING(int)The Framed-Routing attribute. The attribute value is expected to be anintindicating the routing method for the user, which can be set usingradius_put_int().
Possible values include:
0: No routing1: Send routing packets2: Listen for routing packets3: Send and listenRADIUS_FILTER_ID(int)The Filter-ID attribute. The attribute value is expected to be an implementation-specific, human-readablestringof filters, which can be set usingradius_put_attr().
RADIUS_FRAMED_MTU(int)The Framed-MTU attribute. The attribute value is expected to be anintindicating the MTU to be configured for the user, and can be set usingradius_put_int().
RADIUS_FRAMED_COMPRESSION(int)The Framed-Compression attribute. The attribute value is expected to be anintindicating the compression protocol to be used, and can be set usingradius_put_int(). Possible values include these constants:
RADIUS_COMP_NONE: No compressionRADIUS_COMP_VJ: VJ TCP/IP header compressionRADIUS_COMP_IPXHDR: IPX header compressionRADIUS_COMP_STAC_LZS: Stac-LZS compression (added in PECL radius 1.3.0b2)RADIUS_LOGIN_IP_HOST(int)The Login-IP-Host attribute. The attribute value is expected to the IP address to connect the user to, encoded as anint, which can be set usingradius_put_addr().
RADIUS_LOGIN_SERVICE(int)The Login-Service attribute. The attribute value is anintindicating the service to connect the user to on the login host. The value can be converted to a PHP integer viaradius_cvt_int().
RADIUS_LOGIN_TCP_PORT(int)The Login-TCP-Port attribute. The attribute value is anintindicating the port to connect the user to on the login host. The value can be converted to a PHP integer viaradius_cvt_int().
RADIUS_REPLY_MESSAGE(int)The Reply-Message attribute. The attribute value is astringcontaining text that may be displayed to the user in response to an access request.
RADIUS_CALLBACK_NUMBER(int)The Callback-Number attribute. The attribute value is astringcontaining the dialing string to use for callback.
RADIUS_CALLBACK_ID(int)The Callback-Id attribute. The attribute value is astringcontaining an implementation-specific name of the place to be called.
RADIUS_FRAMED_ROUTE(int)The Framed-Route attribute. The attribute value is astringcontaining an implementation-specific set of routes to be configured for the user.
RADIUS_FRAMED_IPX_NETWORK(int)The Framed-IPX-Network attribute. The attribute value is anintcontaining the IPX network to be configured for the user, or0xFFFFFFFEto indicate that the RADIUS client should select the network, and can be accessed viaradius_cvt_int().
RADIUS_STATE(int)The State attribute. The attribute value is an implementation-definedstringincluded in an Access-Challenge from a server that must be included in the subsequent Access-Request, and can be set usingradius_put_attr().
RADIUS_CLASS(int)The Class attribute. The attribute value is an arbitrarystringincluded in an Access-Accept message that should then be sent to the accounting server in Accounting-Request messages, and can be set usingradius_put_attr().
RADIUS_VENDOR_SPECIFIC(int)The Vendor-Specific attribute. In general, vendor attribute values should be set usingradius_put_vendor_addr(),radius_put_vendor_attr(),radius_put_vendor_int()andradius_put_vendor_string(), rather than directly.
This constant is mostly useful when interpreting vendor specific attributes in responses from a RADIUS server; when a vendor specific attribute is received, theradius_get_vendor_attr()function should be used to access the vendor ID, attribute type and attribute value.
RADIUS_SESSION_TIMEOUT(int)Session timeout
RADIUS_IDLE_TIMEOUT(int)Idle timeout
RADIUS_TERMINATION_ACTION(int)Termination action
RADIUS_CALLED_STATION_ID(int)Called Station Id
RADIUS_CALLING_STATION_ID(int)Calling Station Id
RADIUS_NAS_IDENTIFIER(int)NAS ID
RADIUS_PROXY_STATE(int)Proxy State
RADIUS_LOGIN_LAT_SERVICE(int)Login LAT Service
RADIUS_LOGIN_LAT_NODE(int)Login LAT Node
RADIUS_LOGIN_LAT_GROUP(int)Login LAT Group
RADIUS_FRAMED_APPLETALK_LINK(int)Framed Appletalk Link
RADIUS_FRAMED_APPLETALK_NETWORK(int)Framed Appletalk Network
RADIUS_FRAMED_APPLETALK_ZONE(int)Framed Appletalk Zone
RADIUS_CHAP_CHALLENGE(int)Challenge
RADIUS_NAS_PORT_TYPE(int)NAS port type, one of:
RADIUS_ASYNCRADIUS_SYNCRADIUS_ISDN_SYNCRADIUS_ISDN_ASYNC_V120RADIUS_ISDN_ASYNC_V110RADIUS_VIRTUALRADIUS_PIAFSRADIUS_HDLC_CLEAR_CHANNELRADIUS_X_25RADIUS_X_75RADIUS_G_3_FAXRADIUS_SDSLRADIUS_ADSL_CAPRADIUS_ADSL_DMTRADIUS_IDSLRADIUS_ETHERNETRADIUS_XDSLRADIUS_CABLERADIUS_WIRELESS_OTHERRADIUS_WIRELESS_IEEE_802_11RADIUS_PORT_LIMIT(int)Port Limit
RADIUS_LOGIN_LAT_PORT(int)Login LAT Port
RADIUS_CONNECT_INFO(int)Connect info
RADIUS_ACCT_STATUS_TYPE(int)Accounting status type, one of:
RADIUS_STARTRADIUS_STOPRADIUS_ACCOUNTING_ONRADIUS_ACCOUNTING_OFFRADIUS_ACCT_DELAY_TIME(int)Accounting delay time
RADIUS_ACCT_INPUT_OCTETS(int)Accounting input bytes
RADIUS_ACCT_OUTPUT_OCTETS(int)Accounting output bytes
RADIUS_ACCT_SESSION_ID(int)Accounting session ID
RADIUS_ACCT_AUTHENTIC(int)Accounting authentic, one of:
RADIUS_AUTH_RADIUSRADIUS_AUTH_LOCALRADIUS_AUTH_REMOTERADIUS_ACCT_SESSION_TIME(int)Accounting session time
RADIUS_ACCT_INPUT_PACKETS(int)Accounting input packets
RADIUS_ACCT_OUTPUT_PACKETS(int)Accounting output packets
RADIUS_ACCT_TERMINATE_CAUSE(int)Accounting terminate cause, one of:
RADIUS_TERM_USER_REQUESTRADIUS_TERM_LOST_CARRIERRADIUS_TERM_LOST_SERVICERADIUS_TERM_IDLE_TIMEOUTRADIUS_TERM_SESSION_TIMEOUTRADIUS_TERM_ADMIN_RESETRADIUS_TERM_ADMIN_REBOOTRADIUS_TERM_PORT_ERRORRADIUS_TERM_NAS_ERRORRADIUS_TERM_NAS_REQUESTRADIUS_TERM_NAS_REBOOTRADIUS_TERM_PORT_UNNEEDEDRADIUS_TERM_PORT_PREEMPTEDRADIUS_TERM_PORT_SUSPENDEDRADIUS_TERM_SERVICE_UNAVAILABLERADIUS_TERM_CALLBACKRADIUS_TERM_USER_ERRORRADIUS_TERM_HOST_REQUESTRADIUS_ACCT_MULTI_SESSION_ID(int)Accounting multi session ID
RADIUS_ACCT_LINK_COUNT(int)Accounting link count
RADIUS_VENDOR_MICROSOFT(int)Microsoft specific vendor attributes (» RFC 2548), one of:
RADIUS_MICROSOFT_MS_CHAP_RESPONSERADIUS_MICROSOFT_MS_CHAP_ERRORRADIUS_MICROSOFT_MS_CHAP_PW_1RADIUS_MICROSOFT_MS_CHAP_PW_2RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PWRADIUS_MICROSOFT_MS_CHAP_NT_ENC_PWRADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICYRADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPESRADIUS_MICROSOFT_MS_RAS_VENDORRADIUS_MICROSOFT_MS_CHAP_DOMAINRADIUS_MICROSOFT_MS_CHAP_CHALLENGERADIUS_MICROSOFT_MS_CHAP_MPPE_KEYSRADIUS_MICROSOFT_MS_BAP_USAGERADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLDRADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMITRADIUS_MICROSOFT_MS_MPPE_SEND_KEYRADIUS_MICROSOFT_MS_MPPE_RECV_KEYRADIUS_MICROSOFT_MS_RAS_VERSIONRADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORDRADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORDRADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASONRADIUS_MICROSOFT_MS_FILTERRADIUS_MICROSOFT_MS_ACCT_AUTH_TYPERADIUS_MICROSOFT_MS_ACCT_EAP_TYPERADIUS_MICROSOFT_MS_CHAP2_RESPONSERADIUS_MICROSOFT_MS_CHAP2_SUCCESSRADIUS_MICROSOFT_MS_CHAP2_PWRADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVERRADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVERRADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVERRADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVERRADIUS_MICROSOFT_MS_ARAP_CHALLENGE¿Cómo iniciar?
El paquete contiene un ejemplo de script php. Este script demuestra como autenticar con radius utilizando PAP o CHAP (md5). Si se autentica con servidores Microsoft Radius entonces no le será posible utilizar CHAP (md5). Si quisiera autenticarse con servidores Microsoft tiene que utilizar MS-CHAPv1 o MS-CHAPv2, pero es más complicado, porque usted necesita md4, sha1 y des para generar los datos correctos. Los ejemplos adjuntos demuestran todos los métodos de autenticación, incluyendo MS-CHAPv1 y MS-CHAPv2. Para tener funcionando MS-CHAP necesita las extensionesmcryptymhashiniciando con la version 1.2 de este paquete, la extensión mcrypt ya no es necesaria.
(PECL radius >= 1.1.0)
radius_acct_open—Crea un manejador Radius para el conteo
Devuelve un manejador en caso de tener éxito,falseen caso de error. Esta función falla solamente si hay insuficiencia de memoria.
Ejemplo #1radius_acct_open()example
<?php
$res=radius_acct_open()
or die ("No se pudo crear un manejador handle");
print("Manejador creado exitosamente");
?>(PECL radius >= 1.1.0)
radius_add_server—Adds a server
$radius_handle,$hostname,$port,$secret,$timeout,$max_triesradius_add_server()may be called multiple times, and it may be used together withradius_config(). At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server'smax_trieslimit has been reached.
radius_handlehostnameThehostnameparameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.
portTheportspecifies the UDP port to contact on the server. If port is given as 0, the library looks up theradius/udporradacct/udpservice in the network services database, and uses the port found there. If no entry is found, the library uses the standard Radius ports, 1812 for authentication and 1813 for accounting.
secretThe shared secret for the server host is passed to thesecretparameter. The Radius protocol ignores all but the leading 128 bytes of the shared secret.
timeoutThe timeout for receiving replies from the server is passed to thetimeoutparameter, in units of seconds.
max_triesThe maximum number of repeated requests to make before giving up is passed into themax_tries.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1radius_add_server()example
<?php
if (!radius_add_server($res,'radius.example.com',1812,'testing123',3,3)) {
echo'RadiusError:'.radius_strerror($res)."\n<br>";
exit;
}
?>(PECL radius >= 1.1.0)
radius_auth_open—Crea un identificador de Radius para la autenticación
Devuelve un manejador en caso de éxito,falseen caso de error. Esta función sólo falla si hay insuficiente memoria disponible.
Ejemplo #1 Ejemplo deradius_auth_open()
<?php
$radh=radius_auth_open()
or die ("No se pudo crear el manejador");
echo"Manejador creado con éxito";
?>(PECL radius >= 1.1.0)
radius_close—Libera todos los recursos
$radius_handle):boolNo es necesario llamar a esta función debido a que php libera todos los recursos al final de cada petición.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL radius >= 1.1.0)
radius_config—Causes the library to read the given configuration file
$radius_handle,string$file):boolBefore issuing any Radius requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to callradius_config().radius_config()causes the library to read a configuration file whose format is described in» radius.conf.
radius_handlefileThe pathname of the configuration file is passed as the file argument toradius_config(). The library can also be configured programmatically by calls toradius_add_server().
Devuelvetrueen caso de éxito ofalseen caso de error.
(PECL radius >= 1.1.0)
radius_create_request—Create accounting or authentication request
$radius_handle,int$type):boolA Radius request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, callradius_create_request().
Nota:Attention: You must call this function, before you can put any attribute!
radius_handletypeType isRADIUS_ACCESS_REQUESTorRADIUS_ACCOUNTING_REQUEST.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1radius_create_request()example
<?php
if (!radius_create_request($res,RADIUS_ACCESS_REQUEST)) {
echo'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>(PECL radius >= 1.1.0)
radius_cvt_addr—Converts raw data to IP-Address
$data):stringConverts raw data to IP-Address
dataInput data
Returns the IP-Address.
Ejemplo #1radius_cvt_addr()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
switch ($attr) {
caseRADIUS_FRAMED_IP_ADDRESS:
$ip=radius_cvt_addr($data);
echo"IP:$ip<br>\n";
break;
caseRADIUS_FRAMED_IP_NETMASK:
$mask=radius_cvt_addr($data);
echo"MASK:$mask<br>\n";
break;
}
}
?>(PECL radius >= 1.1.0)
radius_cvt_int—Converts raw data to integer
$data):intConverts raw data to integer
dataInput data
Returns the integer, retrieved from data.
Ejemplo #1radius_cvt_int()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
switch ($attr) {
caseRADIUS_FRAMED_MTU:
$mtu=radius_cvt_int($data);
echo"MTU:$mtu<br>\n";
break;
}
}
?>(PECL radius >= 1.1.0)
radius_cvt_string—Converts raw data to string
$data):stringConverts raw data to string
dataInput data
Returns the string, retrieved from data.
Ejemplo #1radius_cvt_string()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
switch ($attr) {
caseRADIUS_FILTER_ID:
$id=radius_cvt_string($data);
echo"Filter ID:$id<br>\n";
break;
}
}
?>(PECL radius >= 1.2.0)
radius_demangle_mppe_key—Derives mppe-keys from mangled data
$radius_handle,string$mangled):stringWhen using MPPE with MS-CHAPv2, the send- and recv-keys are mangled (see» RFC 2548), however this function is useless, because I don't think that there is or will be a PPTP-MPPE implementation in PHP.
radius_handleEl recurso RADIUS.
mangledThe mangled data to demangle
Returns the demangled string, orfalseon error.
(PECL radius >= 1.2.0)
radius_demangle—Demangles data
$radius_handle,string$mangled):stringSome data (Passwords, MS-CHAPv1 MPPE-Keys) is mangled for security reasons, and must be demangled before you can use them.
radius_handleEl recurso RADIUS.
mangledThe mangled data to demangle
Returns the demangled string, orfalseon error.
(PECL radius >= 1.1.0)
radius_get_attr—Extracts an attribute
Like Radius requests, each response may contain zero or more attributes. After a response has been received successfully byradius_send_request(), its attributes can be extracted one by one usingradius_get_attr(). Each timeradius_get_attr()is called, it gets the next attribute from the current response.
radius_handleEl recurso RADIUS.
Returns an associative array containing the attribute-type and the data, or error number <= 0.
Ejemplo #1radius_get_attr()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
printf("Got Attr:%d %d Bytes %s\n",$attr,strlen($data),bin2hex($data));
}
?>(PECL radius >= 1.3.0)
radius_get_tagged_attr_data—Extracts the data from a tagged attribute
$data):string|falseIf a tagged attribute has been returned fromradius_get_attr(),radius_get_tagged_attr_data()will return the data from the attribute.
dataThe tagged attribute to be decoded.
Returns the data from the tagged attribute ofalseen caso de error.
Ejemplo #1radius_get_tagged_attr_data()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
$tag=radius_get_tagged_attr_tag($data);
$value=radius_get_tagged_attr_data($data);
printf("Got tagged attribute with tag %d and value %s\n",$tag,$value);
}
?>(PECL radius >= 1.3.0)
radius_get_tagged_attr_tag—Extracts the tag from a tagged attribute
$data):int|falseIf a tagged attribute has been returned fromradius_get_attr(),radius_get_tagged_attr_data()will return the tag from the attribute.
dataThe tagged attribute to be decoded.
Returns the tag from the tagged attribute ofalseen caso de error.
Ejemplo #1radius_get_tagged_attr_tag()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
$tag=radius_get_tagged_attr_tag($data);
$value=radius_get_tagged_attr_data($data);
printf("Got tagged attribute with tag %d and value %s\n",$tag,$value);
}
?>(PECL radius >= 1.1.0)
radius_get_vendor_attr—Extracts a vendor specific attribute
$data):arrayIfradius_get_attr()returnsRADIUS_VENDOR_SPECIFIC,radius_get_vendor_attr()may be called to determine the vendor.
dataInput data
Returns an associative array containing the attribute-type, vendor and the data, orfalseon error.
Ejemplo #1radius_get_vendor_attr()example
<?php
while ($resa=radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}
$attr=$resa['attr'];
$data=$resa['data'];
printf("Got Attr:%d %d Bytes %s\n",$attr,strlen($data),bin2hex($data));
if ($attr==RADIUS_VENDOR_SPECIFIC) {
$resv=radius_get_vendor_attr($data);
if (is_array($resv)) {
$vendor=$resv['vendor'];
$attrv=$resv['attr'];
$datav=$resv['data'];
printf("Got Vendor Attr:%d %d Bytes %s\n",$attrv,strlen($datav),bin2hex($datav));
}
}
}
?>(PECL radius >= 1.1.0)
radius_put_addr—Attaches an IP address attribute
$radius_handle,$type,$addr,$options= 0,$tag= ?Attaches an IP address attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
typeEl tipo de atributo.
addrAn IPv4 address in string form, such as10.0.0.1.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
(PECL radius >= 1.1.0)
radius_put_attr—Attaches a binary attribute
$radius_handle,$type,$value,$options= 0,$tag= ?Attaches a binary attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
typeEl tipo de atributo.
valueThe attribute value, which will be treated as a raw binary string.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
Ejemplo #1radius_put_attr()example
<?php
mt_srand(time());
$chall=mt_rand();
$chapval=md5(pack('Ca*',1,'sepp'.$chall));
$pass=pack('CH*',1,$chapval);
if (!radius_put_attr($res,RADIUS_CHAP_PASSWORD,$pass)) {
echo'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>(PECL radius >= 1.1.0)
radius_put_int—Attaches an integer attribute
$radius_handle,$type,$value,$options= 0,$tag= ?Attaches an integer attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
typeEl tipo de atributo.
valueThe attribute value.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
Ejemplo #1radius_put_int()example
<?php
if (!radius_put_int($res,RAD_FRAMED_PROTOCOL,RAD_PPP)) {
echo'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>(PECL radius >= 1.1.0)
radius_put_string—Attaches a string attribute
$radius_handle,$type,$value,$options= 0,$tag= ?Attaches a string attribute to the current RADIUS request. In general,radius_put_attr()is a more useful function for attaching string attributes, as it is binary safe.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
typeEl tipo de atributo.
valueThe attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
Ejemplo #1radius_put_string()example
<?php
if (!radius_put_string($res,RADIUS_USER_NAME,'billy')) {
echo'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>(PECL radius >= 1.1.0)
radius_put_vendor_addr—Attaches a vendor specific IP address attribute
$radius_handle,$vendor,$type,$addrAttaches an IP address vendor specific attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
vendorEl ID del vendedor.
typeEl tipo de atributo.
addrAn IPv4 address in string form, such as10.0.0.1.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
(PECL radius >= 1.1.0)
radius_put_vendor_attr—Attaches a vendor specific binary attribute
$radius_handle,$vendor,$type,$value,$options= 0,$tag= ?Attaches a vendor specific binary attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
vendorEl ID del vendedor.
typeEl tipo de atributo.
valueThe attribute value, which will be treated as a raw binary string.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
Ejemplo #1radius_put_vendor_attr()example
<?php
if (!radius_put_vendor_attr($res,RADIUS_VENDOR_MICROSOFT,RAD_MICROSOFT_MS_CHAP_CHALLENGE,$challenge)) {
echo'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>(PECL radius >= 1.1.0)
radius_put_vendor_int—Attaches a vendor specific integer attribute
$radius_handle,$vendor,$type,$value,$options= 0,$tag= ?Attaches a vendor specific integer attribute to the current RADIUS request.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
vendorEl ID del vendedor.
typeEl tipo de atributo.
valueThe attribute value.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
(PECL radius >= 1.1.0)
radius_put_vendor_string—Attaches a vendor specific string attribute
$radius_handle,$vendor,$type,$value,$options= 0,$tag= ?Attaches a vendor specific string attribute to the current RADIUS request. In general,radius_put_vendor_attr()is a more useful function for attaching string attributes, as it is binary safe.
Nota:
Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.
radius_handleEl recurso RADIUS.
vendorEl ID del vendedor.
typeEl tipo de atributo.
valueThe attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
optionsUna máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.
tagLA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| PECL radius 1.3.0 | Theoptionsandtagparameters were added. |
(PECL radius >= 1.1.0)
radius_request_authenticator—Returns the request authenticator
$radius_handle):stringThe request authenticator is needed for demangling mangled data like passwords and encryption-keys.
radius_handleEl recurso RADIUS.
Returns the request authenticator as string, orfalseon error.
(PECL radius >= 1.3.0)
radius_salt_encrypt_attr—Salt-encrypts a value
$radius_handle,string$data):string|falseApplies the RADIUS salt-encryption algorithm to the given value.
In general, this is achieved automatically by providing theRADIUS_OPTION_SALToption to an attribute setter function, but this function can be used if low-level request construction is required.
dataThe data to be salt-encrypted.
Returns the salt-encrypted data ofalseen caso de error.
(PECL radius >= 1.1.0)
radius_send_request—Sends the request and waits for a reply
$radius_handle):intAfter the Radius request has been constructed, it is sent byradius_send_request().
Theradius_send_request()function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary.
radius_handleEl recurso RADIUS.
If a valid response is received,radius_send_request()returns the Radius code which specifies the type of the response. This will typically beRADIUS_ACCESS_ACCEPT,RADIUS_ACCESS_REJECT, orRADIUS_ACCESS_CHALLENGE. If no valid response is received,radius_send_request()returnsfalse.
(PECL radius >= 1.1.0)
radius_server_secret—Returns the shared secret
$radius_handle):stringThe shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.
radius_handleEl recurso RADIUS.
Returns the server's shared secret as string, orfalseon error.
(PECL radius >= 1.1.0)
radius_strerror—Devuelve un mensaje de error
$radius_handle):stringSi las funciones radio fallan entonces guardan un mensaje de error. Este mensaje de error puede ser obtenido con esta función.
Devuelve mensajes de error como string de funciones radio fallidas.
Las funciones de readline implementan una interfaz a la biblioteca GNU Readline. Estas funciones proporcionan líneas de comando editables. Un ejemplo es Bash, que permite utilizar las teclas de dirección para insertar caracteres o desplazarse a través del historial de comandos. Debido a la naturaleza interactiva de esta biblioteca, será de poca utilidad para la creación de aplicaciones Web, pero puede ser útil cuando se escriben scripts utilizando lalínea de comandos.
A partir de PHP 7.1.0 esta extensión está soportada en Windows.
¡La extensión de la línea de lectura no es segura para el hilo! Por lo tanto, se desaconseja su uso con cualquier SAPI verdaderamente segura para los hilos (como el Apache mod_winnt).
Para usar las funciones readline, es necesario instalar libreadline. Se puede encontrar libreadline en la página principal del proyecto GNU Readline, en» http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. Este proyecto es administrado por Chet Ramey, quien es también el autor de Bash.
También puede utilizar estas funciones con la libreria libedit, un reemplazo no-GPL para la biblioteca readline. La biblioteca libedit tiene licencia BSD y está disponible para su descarga desde» http://www.thrysoee.dk/editline/.
Para utilizar estas funciones, debe compilar la versión CGI o CLI de PHP con soporte para readline. Es necesario configurar PHP--with-readline[=DIR]. Si desea utilizar el reemplazo de readline libedit, es necesario configurar PHP--with-libedit[=DIR].
En Windows esta extensión está disponible por defecto a partir de PHP 7.1.0.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| cli.pager | "" | PHP_INI_ALL | |
| cli.prompt | "\\b \\> " | PHP_INI_ALL |
He aquí una breve explicación de las directivas de configuración.
cli.pagerstringHerramienta externa para mostrar la salida de lalínea de comandos.
cli.promptstringVéaseLínea de Comandos.
Esta extensión no tiene ningún tipo de recurso definido.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
READLINE_LIB(string)readlineolibedit. Disponible a partir de PHP 5.5.0.(PHP 4, PHP 5, PHP 7, PHP 8)
readline_add_history—Agrega una línea a la historia
$line):boolEsta función agrega una línea a la historia de la línea de comandos.
lineLa línea a ser agregada en la historia.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
readline_callback_handler_install—Inicializa la interfaz de llamada de readline y la terminal, imprime el mensaje y retorna inmediatamente
Configura una interfaz de llamada readline y luego imprimemensaje, luego de lo cual retorna. Si llamas a esta función más de una vez sin eliminar la interfaz de llamada anterior automaticamente reemplazará la versión anterior.
La interfaz de llamada es útil cuando se combina constream_select()ya que permite la intercalación de IO (entrada/salida) y entrada del usuario, a diferencia dereadline().
mensajeEl mensaje a imprimir.
funcionLa funciónfuncionrecibe un parámetro; la entrada del usuario retornada.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo de interfaz de llamada readline
<?php
functionrl_callback($ret)
{
global$c,$prompting;
echo"Has ingresado:$ret\n";
$c++;
if ($c>10) {
$prompting=false;
readline_callback_handler_remove();
} else {
readline_callback_handler_install("[$c] Ingresa algo: ",'rl_callback');
}
}
$c=1;
$prompting=true;
readline_callback_handler_install("[$c] Ingresa algo: ",'rl_callback');
while ($prompting) {
$w=NULL;
$e=NULL;
$n=stream_select($r= array(STDIN),$w,$e,null);
if ($n&&in_array(STDIN,$r)) {
// lee un carácter, llama a la funcion cuando una nueva línea es ingresada
readline_callback_read_char();
}
}
echo"Mensaje deshabilitado. Todo hecho.\n";
?>(PHP 5 >= 5.1.0, PHP 7, PHP 8)
readline_callback_handler_remove—Elimina una interfaz de llamada anteriormente agregada y retaura la configuración de terminal
Elimina una interfaz de llamada configurada anteriormente y restaura la configuración de terminal.
Retornatruesi una interfaz de llamada instalada anteriormente fue eliminada, ofalsesi no pudo hallarse una.
Verreadline_callback_handler_install()para un ejemplo sobre como utilizar la interfaz de llamada de readline.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
readline_callback_read_char—Lee un carácter e informa a la interfaz de llamada de readline cuando una línea es recibida
Lee un carácter del usuario. Cuando una línea es recibida, esta función informa a la interfaz de llamada de readline utilizandoreadline_callback_handler_install(), especificando así que hay una línea lista como entrada.
No devuelve ningún valor.
Veásereadline_callback_handler_install()para un ejemplo sobre cómo utilizar la interfaz de llamada de readline.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_clear_history—Limpia el historial
Esta función limpia completamente el historial de línea de comandos.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_completion_function—Registra una función de autocompletado
Esta función reistra una función para ser utilizada para autocompletar comandos. Es la misma funcionalidad que obtendrías si presionas la tecla Tab mientras escribes un comando en Bash.
funcionEl nombre de una función que acepta una línea de comandos parcial y devuelve un array con las entradas coincidentes.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_info—Obtiene/Modifica variables internas a readline
Obtiene o modifica numerosas variables internas de readline.
variableUn nombre de variable.
valorSi se especifica, este será el nuevo valor de la variable.
Si esta función es llamada sin parámetros, retornará un array de valores para todos los usos de readline. Los elementos estarán indexados por los siguientes valores: done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, y terminal_name.
Si es llamado por uno o dos parámetros, el valor anterior de la variable es retornado.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_list_history—Obtener el historial
Obtiene el historial completo de comandos.
Retorna un array correspondiente al historial completo de la línea de comandos. Los elementos son indexados por enteros, comenzando desde cero.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
readline_on_new_line—Informar a readline que el cursor se ha movido a una nueva línea
Le informa a readline que el cursor se ha movido a una nueva línea.
No devuelve ningún valor.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_read_history—Lee el historial
$filename= ?):boolEsta función lee el historial de comandos desde un archivo.
archivoUbicación del archivo que contiene el historial de comandos.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.1.0, PHP 7, PHP 8)
readline_redisplay—Redibuja la vista
Redibuja readline para volver a dibujar la vista.
No devuelve ningún valor.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline_write_history—Escribe el historial
$filename= ?):boolEsta función escribe el historial de comandos en un archivo.
archivoUbicación del archivo.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
readline—Lee una línea
$prompt=null):stringLee una sola línea del usuario. Debe agregar esta línea al historial utilizandoreadline_add_history().
mensajePuedes especificar un mensaje que se muestra al usuario.
Devuelve un único string del usuario. Esta línea retornada tiene el avance de línea al final eliminado.
Ejemplo #1 Ejemplo dereadline()
<?php
//obtener 3 comandos del usuario
for ($i=0;$i<3;$i++) {
$linea=readline("Comando: ");
readline_add_history($linea);
}
//mostrar historial
print_r(readline_list_history());
//mostrar variables
print_r(readline_info());
?>Las funciones de bzip2 se utilizan para leer y escribir ficheros comprimidos con bzip2 (.bz2) de forma transparente.
Este módulo usa las funciones de la librería» bzip2por Julian Seward. Este módulo requiere bzip2/libbzip2 version >= 1.0.x.
El soporte deBzip2en PHP no está activado por defecto. Se necesita usar la opción de configuración--with-bz2[=DIR]al compilar PHP para activar soporte de bzip2.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Esta extensión define un tipo de recurso: apunta a un archivo identificando el fichero bz2 a trabajar.
Esta extensión no tiene ninguna constante definida.
Este ejemplo abre un fichero temporal y escribe una cadena de prueba en el, muestra el contenido del fichero.
Ejemplo #1 Pequeño ejemplo de bzip2
<?php
$filename="/tmp/testfile.bz2";
$str="Esto es una cadena de prueba.\n";
// Abriendo fichero para escribir
$bz=bzopen($filename,"w");
// escribe la cadena en el fichero
bzwrite($bz,$str);
// cierra el fichero
bzclose($bz);
// abre el fichero para escritura
$bz=bzopen($filename,"r");
// lee 10 caracteres
echobzread($bz,10);
// muestra salida hasta el final del fichero (o los siguientes 1024 caracteres) y lo cierra.
echobzread($bz);
bzclose($bz);
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzclose—Cierra un fichero bzip2
$bz):boolCierra el dado puntero del fichero bzip2.
bzEl puntero del fichero. Debe ser un puntero válido a un fichero abierto conbzopen()satisfactoriamente.
Devuelvetrueen caso de éxito ofalseen caso de error.
(No version information available, might only be in Git)
bzcompress—Comprime una cadena en datos codificados en bzip2
bzcompress()comprime la cadena dada y la devuelve como datos codificados con bzip2.
sourceLa cadena a comprimir.
blocksizeEspecifica el blocksize usado durante la compresión y debería ser un número entre 1 y 9 siendo 9 la máxima compresión, pero también utiliza más recursos.
workfactorControla como se comportan las fases de compresión cuando se presenta en el peor de los casos, datos que se repiten continuamente. El valor puede estar entre 0 y 250 siendo 0 un caso especial.
Independientemente deworkfactor, el valor generado de salida es el mismo.
La cadena comprimida, o el número de error en caso de error.
Ejemplo #1 Comprimiendo datos
<?php
$str="sample data";
$bzstr=bzcompress($str,9);
echo$bzstr;
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzdecompress—Descomprime datos codificados con bzip2
bzdecompress()descomprime el string pasado por parámetro que contiene los datos codificados en bzip2.
sourceString a descomprimir.
smallSi estrue, se usará un algoritmo de descompresión alternativo que utiliza menos memoria (disminuye el requisito máximo de memoria a entorno a 2300K) pero por otra parte es la mitad de lento aproximadamente.
Consulte la» documentación de bzip2para más información sobre este comportamiento.
El string descromprimido, o el número de error en caso de error.
Ejemplo #1 Descompresión de un String
<?php
$start_str="This is not an honest face?";
$bzstr=bzcompress($start_str);
echo"String Comprimido: ";
echo$bzstr;
echo"\n<br />\n";
$str=bzdecompress($bzstr);
echo"String Descomprimido: ";
echo$str;
echo"\n<br />\n";
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzerrno—Devuelve el número de erro de bzip2
$bz):intDevuelve el número de error de cualquier error bzip2 devuelto por el puntero del fichero dado.
bzEl puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.
Devuelve el número de error como entero.
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzerror—Devuelve el número de error y la cadena del error de bzip2 en un array
$bz):arrayDevuelve el número de error y la cadena de error de cualquier error bzip2 devuelto por el puntero del fichero dado.
bzEl puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.
Devuelve un array asociativo, con el código de error en la entradaerrnoy el mensaje de error en la entradaerrstr.
Ejemplo #1 Ejemplo debzerror()
<?php
$error=bzerror($bz);
echo$error["errno"];
echo$error["errstr"];
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzerrstr—Devuelve una cadena de error de bzip2
$bz):stringObtiene la cadena de error de cualquier error bzip2 devuelto por el puntero dado.
bzEl puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.
Devuelve una cadena que contiene el mensaje de error.
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzflush—Fuerza la escritura de todos los datos del búfer
$bz):boolFuerza la escritura de todos los datos del búfer bzip2 para el puntero del ficherobz.
bzEl puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzopen—Abre un fichero comprimido con bzip2
$filename,string$mode):resourcebzopen()abre un fichero bzip2 (.bz2) para lectura o escritura.
filenameEl nombre del fichero a abrir, o un recurso de flujo existente.
modeSimilar a la funciónfopen(), solamente 'r' (lectura) y 'w' (escritura) están soportados. Todo lo demás hará que bzopen devuelvafalse.
Si al abrir el fichero se produce un error,bzopen()devolveráfalse, en caso contrario devolverá el puntero del nuevo fichero abierto.
Ejemplo #1 Ejemplo debzopen()
<?php
$file="/tmp/foo.bz2";
$bz=bzopen($file,"r") or die("No se pudo abrir el fichero$filepara lectura");
bzclose($bz);
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzread—Lectura segura de ficheros bzip2
$bz,int$length= 1024):stringbzread()lee del puntero de fichero bzip2 pasado como parámetro.
La lectura finaliza una vez que se han leídolengthbytes (descomprimidos) o cuando se alcanza EOF, lo primero que suceda.
bzEl puntero al fichero. Tiene que ser válido y debe apuntar a un fichero que se haya abierto con éxito conbzopen().
lengthSi no se especifica,bzread()leerá bloques de 1024 bytes (descomprimidos) al momento. Un máximo de 8192 bytes descomprimidos serán leídos.
Devuelve la información descomprimida, ofalseen caso de error.
Ejemplo #1 ejemplo debzread()
<?php
$file="/tmp/foo.bz2";
$bz=bzopen($file,"r") or die("No se ha podido abrir$file");
$decompressed_file='';
while (!feof($bz)) {
$decompressed_file.=bzread($bz,4096);
}
bzclose($bz);
echo"El contenido de$filees: <br />\n";
echo$decompressed_file;
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
bzwrite—Escribe en un fichero bzip2 de forma segura binariamente
$bz,string$data,int$length= ?):intbzwrite()escribe una cadena en el fichero gzip2 dado.
bzEl puntero del fichero. Debe apuntar a un fichero abierto satisfactoriamente conbzopen().
dataLos datos a escribir.
lengthSi se proporciona, la escritura terminará después de que ellength(no comprimido) en bytes hayan sido escritos o se haya llegado al final dedata, lo que llegue primero.
Devuelve el número de bytes escritos, ofalseen caso de error.
Ejemplo #1 Ejemplo debzwrite()
<?php
$str="uncompressed data";
$bz=bzopen("/tmp/foo.bz2","w");
bzwrite($bz,$str,strlen($str));
bzclose($bz);
?>LZF es un algoritmo de compresión muy rápido, ideal para ahorrar espacio con solamente un ligero costo de velocidad. Puede optimizarse para velocidad o espacio a la hora de compilar. Esta extensión utiliza la librería» liblzfpor Marc Lehmann para sus operaciones.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
Esta extensión» PECLno se distribuye con PHP. Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/lzf.
Pata utilizar estas funciones se debe compilar PHP con soporte para lzf empleando la opción de configuración--with-lzf[=DIR]. También se puede pasar--enable-lzf-better-compressionpara optimizar LZF para espacio en vez de para velocidad.
Los usuarios de Windows habilitaránphp_lzf.dlldentro dephp.inipara utilizar estas funciones. Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Esta extensión no tiene ningún tipo de recurso definido.
Esta extensión no tiene ninguna constante definida.
(PECL lzf >= 0.1.0)
lzf_compress—Compresión LZF
$data):stringlzf_compress()comprime el stringdatadado utilizando codificación LZF.
dataEl string a comprimir.
Devuelve los datos comprimidos ofalsesi ocurrió un error.
(PECL lzf >= 0.1.0)
lzf_decompress—Descompresión LZF
$data):stringlzf_compress()descomprime la cadenadatadada que contiene los datos codificados en lzf.
dataLa cadena comprimida.
Devuelve los datos descomprimidos ofalsesi ocurrió un error.
(PECL lzf >= 1.0.0)
lzf_optimized_for—Determina para qué fue optimizada la extensión LZF
Determina para qué fue optimizada la extensión LZF durante la compilación.
Devuelve 1 si LZF fue optimizada para velocidad, 0 para compresión.
La extensión phar proporciona una manera de colocar aplicaciones PHP enteras dentro de un único fichero llamado "phar" (PHP Archive) para una distribución e instalación sencillas. Además de proporcionar este servicio, la extensión phar también provee de un método de abstracción de formato de fichero para crear y manipular ficheros tar y zip a través de la clasePharData, tal como PDO proporciona una interfaz unificada para acceder a diferentes bases de datos. A diferencia de PDO, la cual no puede realizar conversiones entre bases de datos diferentes, Phar también realiza conversiones entre los formatos de ficheros tar, zip phar con una sencilla línea de código. VéasePhar::convertToExecutable()para un ejemplo.
¿Qué es phar? Lo archivos Phar están mejor caracterizados como una forma conveniente de agrupar varios ficheros en un único fichero. Como tal, un archvo phar proporciona una forma para distribuir una aplicación PHP completa en un único fichero y ejecutarla desde ese mismo fichero sin necesidad de extraerlo en el disco. Además, los archivos phar pueden ser ejecutados por PHP fácilmente al igual que cualquier otro fichero, tanto desde la línea de comandos como desde un servidor web. Phar a web server. Phar es como una memoria USB para aplicaciones PHP.
Phar implementa esta funcionalidad a través de unaEnvoltura de Flujo. Normalmente, para utilizar un fichero externo dentro de un script de PHP, se debería usarinclude
Ejemplo #1 Utilizar un fichero externo
<?php
include'/ruta/al/fichero/externo.php';
?>Puede considerarse que PHP traduce realemte/ruta/al/fichero/externo.phpa una envoltura de flujo comofile:///ruta/al/fichero/externo.php, y bajo la cubierta de hecho hace uso de funciones de flujo de envolturas de flujo de ficheros para acceder a todos los ficheros locales.
Para utilizar un fichero llamadofichero.phpcontenido en un archivo phar/ruta/a/miphar.phar, la sintaxis es muy similar a la sintaxisfile://de arriba.
Ejemplo #2 Utilizar un fichero dentro de un archivo phar
<?php
include'phar:///ruta/a/miphar.phar/fichero.php';
?>De hecho, se puede tratar un archivo phar exactamente como si fuera un disco externo, usando cualquiera de las funciones relacionadas confopen(),opendir()y funciones relacionadas conmkdir()para leer, cambiar, o crear nuevos ficheros y directorios dentro del archivo phar. Esto permite que aplicaciones de PHP completas sean distribuidas en un único fichero y ejecutarlas directamente desde ese fichero.
El uso más común de un archivo phar es distribuir una aplicación completa en un único fichero. Por ejemplo, el Instalador de PEAR que se incluye con las versiones de PHP está distribuido como un archivo phar. Para usar un archivo phar distribuido de esta forma, se puede ejecutar en línea de comandos o mediante un servidor web.
Los archivos phar pueden ser distribuidos como archivostar,zip, o como formato de ficheropharpersonalizado diseñado específicamente por la extensión phar. Cada formato de fichero tiene sus ventajas y desventajas. Los formatos de fichero tar y zip se pueden leer o extraer mediante cualquier herramienta de terceros que pueda leer el formato, pero necesia la extensión phar para ejecutarlo con PHP. El formato de fichero phar es personalizado y único para la extensión phar, y sólo puede ser creado por la extensión phar o el paquete de PEAR» PHP_Archive, pero tiene la ventaja de que las apliaciones creadas en este formato se ejecutarán incluso si la extensión phar no está habilitada.
En otras palabra, incluso con la extensión phar deshabilitada, se puede ejecutar o incluir un archivo basado en phar. El acceso a ficheros dentro de un archivo phar solamente es posible con la extesnión phar a menos que el archivo phar fuese creado por PHP_Archive.
La extensión phar también es capaz de convertir un archivo phar desde los formatos de fichero tar a zip o a phar en un único comando:
Ejemplo #3 Convertir un archivo phar, desde phar al formato de fichero tar
<?php
$phar= newPhar('miphar.phar');
$pgz=$phar->convertToExecutable(Phar::TAR,Phar::GZ);// crea miphar.phar.tar.gz
?>Phar puede comprimir ficheros individuales o un archivo entero usando la compresióngzipo labzip2, y puede verificar la integridad del archivo automáticamente a través del uso de las signaturas MD5, SHA-1, SHA-256 o SHA-512.
Por último, la extensión Phar se preocupa de la seguridad, y deshabilita el acceso a la escritura de archivos phar ejecutables de manera predeterminada, y requiere la deshabilitación a nivel de sistema del ajustephar.readonlyde php.ini para crear o modificar archivos phar. Los archivos tar y zip normales sin una rutina de interoperabilidad ejecutable siempre pueden ser creador o modificados utilizando la clasePharData.
Si está creando aplicaciones para su distribución, le interesará leerCómo crear Archivos Phar. Si desea más información de las diferencias entre los tres formatos de ficheros que soporta phar, debería leerPhar, Tar y Zip.
Si usa aplicaciones phar, existen consejos útiles enCómo utilizar archivos Phar
La palabraphares una composición dePHPyArchivey está basada indirectamente en el familiarjar(Java Archive) para los desarrolladores Java.
La implementación de archivos Phar está basada en el paquete de PEAR» PHP_Archive, y los detalles de implementación son similares, aunque la extensión Phar es mucho más potente. Además, la extensión Phar permite a la mayoría de las aplicaciones de PHP ejecutarse sin modificaciones, mientras que los archivos phar basados en PHP_Archive a menudo requieren una extensa modificiación para que funcionen.
Phar requiere PHP 5.2.0 o superior. Las caracteristicas adicionales requieren la extensiónSPLpara aprovechar la iteración y el acceso a arrays del contenido de un fichero de Phar. El flujopharno requiere ninguna extensión adicional para que funcione.
Opcionalmente, se puede habilitar las extensioneszlibybzip2para aprovechar el soporte de phar comprimidos. Además, para aprovechar la firma OpenSSL, debe estar habilidata la extensiónOpenSSL.
Observe que un error en el filtro de flujoszlib.deflatecorregido en la versión 5.2.6 y posteriores de PHP puede ocasionar el truncamiento de archivos phar comprimidos con gzip bzip2.
PHP 5.3 configurado con--enable-zend-multibytehace quephardependa de la opción inidetect_unicode.
La extensión Phar está integrada a partir de la versión 5.3.0 de PHP. Phar se puede instalar a través de la extensión PECL con las versiones anteriores de PHP. La» página de PECL de Pharcontiene información adicional y su historia.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| phar.readonly | "1" | PHP_INI_ALL | |
| phar.require_hash | "1" | PHP_INI_ALL | |
| phar.cache_list | "" | PHP_INI_SYSTEM |
He aquí una breve explicación de las directivas de configuración.
phar.readonlyboolEsta opción deshabilita la modificación o creación de archivos Phar usando el flujopharo el soporte para escritura de objetosPhar. Este ajuste debería estar siempre activado en máquinas de producción, ya que el soporte para escritura conveniente de la extensión phar podría permitir la simple creación de un virus basado en PHP al asociarse con otras vulnerabilidades de seguridad comunes.
Nota:
Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Si
phar.readonlyestá deshabilitado en php.ini, un usuario puede habilitarphar.readonlyen un script o deshabilitarlo después. Siphar.readonlyestá habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.
phar.require_hashboolEsta opción forzará a todos los archivos Phar abiertos a que contengan algún tipo de signatura (actualmente está soportadas MD5, SHA1, SHA256 y SHA512), y rehusará procesar cualquer archivo Phar que no contenga una signatura.
Nota:
Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Si
phar.require_hashestá deshabilitado en php.ini, un usuario puede habilitarphar.require_hashen un script o deshabilitarlo después. Siphar.require_hashestá habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.Este ajuste no afecta a la lectura de ficheros tar planos con la clasePharData.
phar.require_hashno proporciona ninguna seguridad per se, es simplemente una medida contra la ejecución accidental de archivos Phar corruptos, porque cualquiera que pueda alterar el Phar podría corregir fácilmente la firma.
phar.cache_liststringPermite mapear archivos phar para que sean preanalizados en el arranque del servidor web, proporcionando una mejora de rendimiento que saca ficheros en ejecución de un archivo phar casi tan rápido como si esos ficheros se ejecutaran desde una instalación tradicional basada en disco.
Ejemplo #1 Ejemplo de uso de phar.cache_list
en php.ini (windows): phar.cache_list =C:\ruta\a\phar1.phar;C:\ruta\a\phar2.phar en php.ini (unix): phar.cache_list =/ruta/a/phar1.phar:/ruta/a/phar2.phar
La extensión Phar proporciona el flujophar, el cual permite el acceso a ficheros contenidos en un phar de manera transparente. Véase también ladescripción de formato de fichero Phar.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
| Constante | Valor | Descripción |
|---|---|---|
Phar::NONE(integer) | 0x00000000 | sin compresión |
Phar::COMPRESSED(integer) | 0x0000F000 | máscara de bit que puede ser usada con banderas de fichero para determinar si está presente algún tipo de compresión |
Phar::GZ(integer) | 0x00001000 | compression zlib (gzip) |
Phar::BZ2(integer) | 0x00002000 | compression bzip2 |
| Constante | Valor | Descripción |
|---|---|---|
Phar::SAME(integer) | 0 | conservar el mismo formato de fichero |
Phar::PHAR(integer) | 1 | formato de fichero phar |
Phar::TAR(integer) | 2 | formato de fichero tar |
Phar::ZIP(integer) | 3 | formato de fichero zip |
| Constante | Valor | Descripción |
|---|---|---|
Phar::MD5(integer) | 0x0001 | singnatura con el algoritmo hash md5 |
Phar::SHA1(integer) | 0x0002 | singnatura con el algoritmo hash sha1 |
Phar::SHA256(integer) | 0x0003 | singnatura con el algoritmo hash sha256 (requiere la extensión Hash) |
Phar::SHA512(integer) | 0x0004 | singnatura con el algoritmo hash sha512 (requiere la extensión Hash) |
Phar::OPENSSL(integer) | 0x0010 | signatura con la pareja de claves pública/privada de OpenSSL. Esta es una signatura de clave asimétrica verdadera. |
| Constante | Valor | Descripción |
|---|---|---|
Phar::PHP(integer) | 1 | usada para ordenar al parámetro de sobrescritura MIME dePhar::webPhar()que la extensión debería ser analizada como un fichero de PHP |
Phar::PHPS(integer) | 2 | usada para ordenar al parámetro de sobrescritura MIME dePhar::webPhar()que la extensión debería ser analizada como un fichero fuente de PHP a través dehighlight_file() |
Los archivos phar son similares en concepto a los archivo JAR de Java, pero están adaptados a las necesidades y a la flexibilidad de aplicaciones de PHP. Un archivo Phar se usa para distribuir una aplicación o biblioteca PHP completa en un único fichero. Una aplicación de un archivo Phar se utiliza exactamente de la misma manera que otra aplicación PHP:
php aplicacion.phar
Utilizar una biblioteca de archivo Phar es idéntico a usar cualquier otra biblioteca de PHP:
<?php
include'biblioteca.phar';
?>La envoltura de flujospharproporciona el núcleo de la extensión Phar, y está explicada en detalleaquí. La envoltura de flujos phar permite el acceso a los ficheros dentro de un archivo phar utilizando las funciones estándar de ficheros de PHPfopen(),opendir(), y y otras que trabajan sobre ficheros normales. La envoltura de flujospharsoporta todas las operaciones de lectura/escritura tanto en ficheros como en directorios.
<?php
include'phar://biblioteca.phar/fichero/interno.php';
header('Content-type: image/jpeg');
// a los phar se puede acceder con la ruta completa o mediante un alias
echofile_get_contents('phar:///ruta_completa/a/biblioteca.phar/imagenes/wow.jpg');
?>La clasePharimplementa una funcionalidad avanzada para acceder a ficheros y crear arhivos phar. La clas Phar está explicada en detalleaquí.
<?php
try {
// abrir un phar existente
$p= newPhar('biblioteca.phar',0);
// Phar extiende la clase DirectoryIterator de SPL
foreach (newRecursiveIteratorIterator($p) as$fichero) {
// $fichero en una clase PharFileInfo, y hereda de SplFileInfo
echo$fichero->getFileName() ."\n";
echofile_get_contents($fichero->getPathName()) ."\n";// mostrar el contenido;
}
if (isset($p['fichero/interno.php'])) {
var_dump($p['fichero/interno.php']->getMetadata());
}
// crear un nuevo phar - phar.readonly debe ser 0 en php.ini
// phar.readonly está habilitado por omisión por motivos de seguridad.
// En servidores de producción, los archivos Phar nunca se crean,
// sólo se ejecutan.
if (Phar::canWrite()) {
$p= newPhar('nuevo_phar.tar.phar',0,'nuevo_phar.tar.phar');
// hacerlo un archivo phar basado en tar, comprimido con gzip (.tar.gz)
$p=$p->convertToExecutable(Phar::TAR,Phar::GZ);
// crear una transacción - no se escribe nada en nuevo_phar.phar
// hasta que stopBuffering() sea llamado, aunque se necesita almacenamiento temporal
$p->startBuffering();
// añadir todos los ficheros de /ruta/del/proyecto, guardándolos en el phar con el prefijo "proyecto"
$p->buildFromIterator(newRecursiveIteratorIterator(newDirectoryIterator('/ruta/del/proyecto')),'/ruta/del/');
// añadir un nuevo fichero mediante la API de acceso a arrays
$p['fichero1.txt'] ='Información';
$fp=fopen('fichero_enorme.dat','rb');
// copiar toda la información del flujo
$p['datos/fichero_enorme.dat'] =$fp;
if (Phar::canCompress(Phar::GZ)) {
$p['datos/fichero_enorme.dat']->compress(Phar::GZ);
}
$p['imagenes/wow.jpg'] =file_get_contents('imagenes/wow.jpg');
// cualquier valor se puede guardar como metainformación específica del fichero
$p['imagenes/wow.jpg']->setMetadata(array('mime-type'=>'image/jpeg'));
$p['index.php'] =file_get_contents('index.php');
$p->setMetadata(array('bootstrap'=>'index.php'));
// cuardar el archivo phar en el disco
$p->stopBuffering();
}
} catch (Exception $e) {
echo'No se pudo abrir Phar: ',$e;
}
?>Además, la verificación del contenido de ficheros phar se puede realizar utilizando cualquiera de los algoritmos hash simétricos soportados (MD5, SHA1, SHA256 y SHA512 si la extensión Hash está habilitada) y utilizando firmas de clave pública/privada asimétricas de OpenSSL (nuevo en Phar 2.0.0). Para aprovechar la firmas de OpenSSL, se necesita generar una pareja de claves pública/privada, y utilizar la clave privada para establecer la firma usandoPhar::setSignatureAlgorithm(). Además, la clave pública se extrae usando este código:
<?php
$public=openssl_get_publickey(file_get_contents('private.pem'));
$pkey='';
openssl_pkey_export($public,$pkey);
?>/ruta/a/mi.phar, la clave pública debe guardarse como/ruta/a/mi.phar.pubkey, o phar no será capaz de verificar la firma OpenSSL.A partir de la verisón 2.0.0, la clasePhartambién proporciona tres métodos estáticos,Phar::webPhar(),Phar::mungServer()yPhar::interceptFileFuncs(), los cuales son cruiciales para empaquetar aplicaciones PHP diseñadas para un uso en sistemas de ficheros normales y aplicación basadas en web.Phar::webPhar()implementa un controlador principal que direcciona llamadas HTTP a la ubicación correcta dentro del archivo phar.Phar::mungServer()se utiliza para modificar los valores del array$_SERVERpara hacer que las aplicaciones procesen estos valores.Phar::interceptFileFuncs()ordena a Phar que intercepte llamdas afopen(),file_get_contents(),opendir(), y a todas las funciones basadas en estadísticas (file_exists(),is_readable(), etc.) y direccione todas las rutas relativas a las ubicaciones dentro del archivo phar.
Como ejemplo, empaquetar una versión de la popular aplicación phpMyAdmin para usarla cono un archivo phar, requiere solamente este sencillo script, y después se puede acceder aphpMyAdmin.phar.tar.phpcomo un fichero normal desde el servidor web después de modificar el usuario/contraseña:
<?php
@unlink('phpMyAdmin.phar.tar.php');
copy('phpMyAdmin-2.11.3-english.tar.gz','phpMyAdmin.phar.tar.php');
$a= newPhar('phpMyAdmin.phar.tar.php');
$a->startBuffering();
$a["phpMyAdmin-2.11.3-english/config.inc.php"] ='<?php
/* Servers configuration */
$i = 0;
/* Server localhost (config:root) [1] */
$i++;
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
$cfg[\'Servers\'][$i][\'compress\'] = false;
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
$cfg[\'Servers\'][$i][\'password\'] = \'\';
/* End of servers configuration */
if (strpos(PHP_OS, \'WIN\') !== false) {
$cfg[\'UploadDir\'] = getcwd();
} else {
$cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
@mkdir(\'/tmp/pharphpmyadmin\');
@chmod(\'/tmp/pharphpmyadmin\', 0777);
}';
$a->setStub('<?php
Phar::interceptFileFuncs();
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
echo "phpMyAdmin está intentando ejecutarse desde un navegador web\n";
exit -1;
__HALT_COMPILER();
');
$a->stopBuffering();
?>La envoltura de flujos phar soporta completamentefopen()para leer y escribir (no añadir),unlink(),stat(),fstat(),fseek(),rename()y operaciones de flujo de directoriosopendir()y a partir de la versión 2.0.0,rmdir()ymkdir().
También se pueden manipular compresiones de ficheros individuales y metadatos por fichero en un archivo Phar usando contextos de flujo:
<?php
$contexto=stream_context_create(array('phar'=>
array('compress'=>Phar::GZ)),
array('metadata'=> array('user'=>'cellog')));
file_put_contents('phar://mi.phar/fichero.php',0,$contexto);
?>La envoltura de flujospharno opera sobre ficheros remotos, y no puede operar sobre ficheros remotos, and cannot operate on remote files, and so is allowed even when theallow_url_fopenandallow_url_includeINI options are disabled.
Aunque es posible crear archivos phar desde cero simplemente usando operaciones de flujos, es mejor utilizar la funcionalidad interna de la clase Phar. La envoltura de flujos se usa mejor para operaciones de sólo lectura.
La clasePharadmite la lectura y la manipulación de archivos Phar, así como la iteración a través de la funcionalidad de la claseRecursiveDirectoryIterator. Con el soporte para la interfazArrayAccess, se puede acceder a los ficheros que están dentro de un archivo Phar como si fueran parte de un array asociativo.
La clasePharDataextiende la clasePhar, y permite crear y modificar archivos tar y zip no ejecutables (datos) incluso siphar.readonly=1 en php.ini. Por lo tanto,PharData::setAlias()yPharData::setStub()están desactivados ya que los conceptos de alias y rutina de interoperabilidad (stub) son válidos únicamente para archivos phar ejecutables.
Observe que al crear un archivo Phar, se debería pasar la ruta completa al contructor del objeto de la clasePhar. Las rutas relativas causarán un error en la inicialización.
Asumiendo que$pes un objeto de la clase Phar inicializado como sigue:
<?php
$p= newPhar('/ruta/a/miphar.phar',0,'miphar.phar');
?>se creará un archivo Phar vacío en/ruta/a/miphar.phar, o si/ruta/a/miphar.pharya existe, se abrirá de nuevo. El literalmiphar.phardemuestra el concepto de un alias que puede ser usado para referenciar a/ruta/a/miphar.pharen URLs, como en:
<?php
// estas dos llamadas a file_get_contents() son equivalentes si
// /ruta/a/miphar.phar tiene un alias especificado como "miphar.phar"
// en su manifiesto, o si el phar fue inicializado con la
// configuración del objeto Phar del ejemplo anterior
$f=file_get_contents('phar:///ruta/a/miphar.phar/loquesea.txt');
$f=file_get_contents('phar://miphar.phar/loquesea.txt');
?>Con el recién creado objeto$pde la clasePhar, lo siguiente es posible:
$a = $p['fichero.php']creates aPharFileInfoclass that refers to the contents ofphar://miphar.phar/fichero.php$p['fichero.php'] = $vcrea un nuevo fichero (phar://miphar.phar/fichero.php), o sobrescribe un fichero existente dentro demiphar.phar.$vpuede ser una cadena o un puntero de fichero abierto, en cuyo caso todo el contenido del fichero se usará para crear el nuevo fichero. Observe que$p->addFromString('fichero.php', $v)es funcionalmente equivalente a lo de más arriba. También es posible añadir el contenido de un fichero con$p->addFile('/path/to/fichero.php', 'fichero.php'). Por ultimo, se puede crear un directorio vacío con$p->addEmptyDir('vacio').isset($p['fichero.php'])se puede usar para determinar siphar://miphar.phar/fichero.phpexiste dentro demiphar.phar.unset($p['fichero.php'])borraphar://miphar.phar/fichero.phpdemiphar.phar.Además, el objeto de la clasePhares la única manera de acceder a metainformación específica de Phar, a través dePhar::getMetadata(), y la única manera de establecer o recuperar una rutina de interoperabilidad (stub) del cargador de PHP de un archivo Phar a través dePhar::getStub()yPhar::setStub(). Además, la compresión del archivo completo Phar de una vez, sólo puede ser manipulada utilizando la clasePhar.
La lista completa de la funcionalidad de objetos de la clasePharestá documentada más adelante.
La clasePharFileInfoextiende a la claseSplFileInfo, y añade varios métodos para manipular detalles específicos de Phar de un fichero contenido en un Phar, tales como la manipulación de la compresión y la metainformación.
Para ser escrita completamente en un futuro próximo. Antes de leer esto, asegúrese de leerComo utilizar archivos PHAR.
Un buen lugar para empezar es leer acerca dePhar::buildFromIterator(), y los detalles de la elección delformato de ficherodisponible para los archivos. Una adecuada comprensión de lo que es y hace una rutina de interoperabilidad (stub), es crucial para la creación de un archivo PHAR, asíPhar::setStub()yPhar::createDefaultStub()son buenos lugares para comenzar. Si va a distribuir una aplicación basada en web es fundamental saber qué es y cómo funcionaPhar::webPhar()y el método relacionadoPhar::mungServer(). Cualquier aplicación que tenga acceso a sus propios ficheros también debe considerar el uso dePhar::interceptFileFuncs().
Todos los archivos Phar contienen tres o cuatro secciones:
una rutina de interoperabilidad (stub)
un manifiesto describiendo el contenido
el contenido de ficheros
[opcional] una firma para verificar la integridad del Phar (solamente el formtado de fichero phar)
Una rutina de interoperabilidad de un Phar es un simple fichero PHP. La rutina de interoperabilidad más pequeña posible es:
<?php__HALT_COMPILER();Una rutina de interoperabilidad debe contener como mínimo el token__HALT_COMPILER();en su conclusión. Normalmente, una rutina de interoperabilidad contendrá funcionalidad cargadora como:
<?php
Phar::mapPhar();
include'phar://miphar.phar/index.php';
__HALT_COMPILER();No existen restricciones para el contenido de una rutina de interoperabilidad de Phar, excepto el requerimiento de que concluya con__HALT_COMPILER();. La etiqueta de cierre de PHPse puede incluir u omitir, pero no puede haber más de un espacio entre el?>
;y la etiqueta de cierreo la extensión phar no podrá procesar el manifiesto del archivo Phar.?>
En un archivo phar basado en tar o zip, la rutina de interoperabilidad es alamcenada en el fichero.phar/stub.php. La rutina de interoperabilidad predeterminada para archivos Phar basados en phar contiene aproximadamente 7k de código para extraer el contenido del phar y ejecutarlo. VéasePhar::createDefaultStub()para más información.
El alias de phar se alamcena en un archivo phar basado en zip en el fichero.phar/alias.txtcomo texto plano.
¿Cuáles son los aspectos positivos y negativos de los tres formatos de fichero soportados en la extensión phar? Esta tabla intenta responder esta pregunta.
| Característica | Phar | Tar | Zip |
|---|---|---|---|
| Formato de Fichero Estádar | No | Sí | Sí |
| Puede ser ejecutado con la extensión Phar[1] | Sí | No | No |
| Compresión por fichero | Sí | No | Sí |
| Compresión de archivo entero | Sí | Sí | No |
| Validación de firmas del archivo entero | Sí | Sí | Sí (PHP 5.3.1+) |
| Soporte para aplicaciones específicas de web | Sí | Sí | Sí |
| Metainformación por fichero | Sí | Sí | Sí |
| Metainformación del archivo entero | Sí | Sí | Sí |
| Modificación creación de archivos[2] | Sí | Sí | Sí |
| Soporte completa para todas las funciones de envoltura de flujos | Sí | Sí | Sí |
| Puede ser creado/modificado incluso si phar.readonly=1[3] | No | Sí | Sí |
[1] PHP solamente puede acceder directamente al contenido de un archivo Phar sin la extensión Phar si está utilizando unarutina de interoperabilidadque extraiga el contenido del archivo phar. La rutina de interoperabilidad creada porPhar::createDefaultStub()extrae el archivo phar y ejecuta su contenido desde un directorio temporal si no se encuentra la extensión phar.
[2] Todos los accesos de escritura requieren quephar.readonlysea deshabilitado en php.ini o directamente or la línea de comandos.
[3] Solamente se pueden crear archivos tar y zip sin.pharen su nombre de fichero y sin una rutina de interoperabilidad ejecutable.phar/stub.phpsi phar.readonly=1.
Los archivos basados en el formato de fichero tar siguen el formato de fichero USTAR más moderno. El diseño de la cabecera de fichero tar los hace más eficientes en el acceso que el formato de fichero zip, y casi tan efiniciente que el formato de fichero phar. Los nombres de fichero están limitados a 255 bytes, incluyentdo la ruta completa dentro de archivo phar. No existe límite en el número de ficheros que un archivo phar basado en tar puede contener. Estos archivos pueden ser comprimidos completamente en los formatos gzip o bzip2 y aún ser ejecutados por la extensión Phar.
Para comprimir un archivo entero, usePhar::compress(). Para descomprimir un archvo entero, usePhar::decompress().
Los archivos basados en el formato de fichero zip soportan varias característica incorporadas del formato de fichero zip. La metainformación por fichero y del archivo entero es almacenda en el comentario del fichero zip y en el comentario del archivo zip como una cadena serializada. Los comentarios zip preexistentes serán leídos de manera satisfactoria como una cadena. La lectura/escritura de la compresión por fichero está soportada con la compresión zlib, y el acceso a lectura está soportado con la compresión bzip2. No existe límite en el número de ficheros que un archivo phar basado en zip puede contener. Los directorios vacíos son almacenados en el archivo zip como ficheros con una barra al final, comomi/directorio/
El formato de fichero phar está dispuesto literalmente como rutina_de_interoperabilidad/manifiesto/contenido/firma, y almacena la información crucial de lo que está incluido en el archivo phar en sumanifiesto.
El manifiesto de phar es un formato altamente optimizado que permite especificaciones por fichero de compresión de ficheros, permisos de ficheros, e incluso metainformación definida por el usuario como el usuario o grupo del fichero. Todos los valores mayores que 1 byte son almacenados en el orden de byte little-endian, con la excepción de la versión de la API, que por motivos históricos es almacenada como 3 en el orden big-endian.
Todas las banderas sin utilizar están reservadas para un uso futuro, y no deben usarse para almacenar información personalizada.to store custom information. Use la característica de metainformación por fichero para alamacenar información personalizada sobre ficheros en particular.
El formato de fichero básico de un manifiesto Phar es como sigue:
| Tamaño en bytes | Descripción |
|---|---|
| 4 bytes | Longitud del manifiesto en bytes (límite 1 MB) |
| 4 bytes | Número de ficheros en el Phar |
| 2 bytes | Versión de la API del manifiesto de Phar (actualmente 1.0.0) |
| 4 bytes | Banderas mapeadas en bit globales de Phar |
| 4 bytes | Longitud del alisa del Phar |
| ?? | Alias del Phar (la longitud basada en lo anterior) |
| 4 bytes | Longitud de la metainformación del Phar (0para ninguna) |
| ?? | Metainformación de Phar serializada, almacenada en el formato deserialize() |
| al menos 24 * número de entradas bytes | entradas para cada fichero |
Aquí están las banderas mapeadas en bit actualmente reconocidas por la extensión Phar para el mapeo de bit plano global de Phar:
| Valor | Descripción |
|---|---|
0x00010000 | Si se establece, el Phar contendrá una firma de verificaición |
0x00001000 | Si se establece, el Phar contendrá al menos 1 fichero que está comprimido con la compresión zlib |
0x00002000 | Si se establece, el Phar contendrá al menos 1 fichero que está comprimido con la compresión bzip |
Cada fichero en el manifiesto contiene la siguiente información:
| Tamaño en bytes | Descripción |
|---|---|
| 4 bytes | Longitud del nombre del fichero en bytes |
| ?? | Nombre del fichero (la longitud especificada en lo anterior) |
| 4 bytes | Tamaño del fichero sin comprimir en bytes |
| 4 bytes | Marca de tiempo Unix del fichero |
| 4 bytes | Tamaño del fichero comprimido en bytes |
| 4 bytes | Suma de verificación CRC32 del contenido del fichero si comprimir |
| 4 bytes | Banderas mapeadas en bit específicas del fichero |
| 4 bytes | Longitud de la metainformación del fichero serializada (0para ninguna) |
| ?? | Metainformación del fichero serializada, almacenada en el formato deserialize() |
Observe que a partir de la versión 1.1.1 de la API, los directorios vacíos son almacenados como nombres de fichero con una barra al final, comomi/directorio/
Los valores de mapeo de bit específicos de fichero reconocidos son:
| Valor | Descripción |
|---|---|
0x000001FF | Estos bits están reservador para la definición de los permisos de fichero específicos de un fichero. Los permisos son usados porfstat()y se pueden utilizar para recrear permisos deseados en la extracción. |
0x00001000 | Si se establece, el fichero es comprimido con la compresión zlib |
0x00002000 | Si se establece, el fichero es comprimido con la compresión bzip |
Los archivos Phar que contienen una firma siempre la tienen añadida al final del archivo Phar después del cargador, el manifiesto y el contenido de ficheros. Los dos formatos de firma soportados en este momento son MD5 y SHA1.
| Longitud en bytes | Descripción |
|---|---|
| 16 ó 20 bytes | La firma real, 20 bytes para una firma SHA1, 16 bytes para una firma MD5, 32 bytes para una firma SHA256, y 64 bytes para una firma SHA512. |
| 4 bytes | Banderas de firma.0x0001se usa para definir una firma MD5,0x0002se usa para definir una firma SHA1,0x0004se usa para definir una firma SHA256, y0x0008se usaupara definir una firma SHA512. El soporte para las firmas SHA256 y SHA512 se introdujo con la versión 1.1.0 de la API. |
| 4 bytes | GBMBmágico usado para definir la presencia de una firma. |
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
La clase Phar proporciona una interfaz de alto nivel para el acceso y la creación de archivos phar.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::addEmptyDir—Añadir un directorio vacío al archvo phar
$dirname):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Con este método se crea un directorio vacío con la ruta dada pordirname. Este método es similar aZipArchive::addEmptyDir().
dirnameEl nombre de directorio vacío a crear en el archivo phar
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePhar::addEmptyDir()
<?php
try {
$a= newPhar('/ruta/a/phar.phar');
$a->addEmptyDir('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->isDir();
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::addFile—Añadir un fichero desde el sistema de ficheros al archivo phar
$file,string$localname= ?):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Con este método, cualquier fichero o URL se puede añadir al arcivo phar. Si se especifica el segundo parámetro opcionallocalname, el fichero será almacenado en el archivo con el nombre dado por el parámetro, si no se usará el parámetrofilecomo la ruta para almacentar dentro del archivo. Las URLs deben tener un nombre local o se lanzará una excepción. Este método es similar aZipArchive::addFile().
fileLa ruta completa o relativa del fichero del disco a ser añadido al archivo phar.
localnameRuta con la que el fichero será almacenado en el archivo.
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePhar::addFile()
<?php
try {
$a= newPhar('/ruta/a/phar.phar');
$a->addFile('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->getContent();
$a->addFile('/ruta/completa/a/fichero','mi/fichero.txt');
$c=$a['mi/fichero.txt']->getContent();
// demostrar el uso de una URL
$a->addFile('http://www.ejemplo.com','ejemplo.html');
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::addFromString—Añadir un fichero desde un string al archivo phar
$localname,string$contents):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Con este método, cuanquierl cadena se puede añadir al archivo phar. El fichero será almacenado en el archivo conlocalnamecomo su ruta. Este método es similar aZipArchive::addFromString().
localnameRuta con la que el fichero será almacenado en el archivo.
contentsEl contenido del fichero a almacenar
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePhar::addFromString()
<?php
try {
$a= newPhar('/ruta/a/phar.phar');
$a->addFromString('ruta/a/fichero.txt','mi sencillo fichero');
$b=$a['ruta/a/fichero.txt']->getContent();
// para añadir contenido desde un gestor de flujos para ficheros grandes, use offsetSet()
$c=fopen('/ruta/a/fichero_enorme.bin');
$a['fichero_grande.bin'] =$c;
fclose($c);
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::apiVersion—Devolver la versión de la API
Devuelve la versión de la API del formato de fichero phar que será usado al crear phars. La extensión Phar soporta la lectura de la versión de la API 1.0.0 o superior. Se requiere la versión 1.1.0 de la API para los algoritmos hash SHA-256 y SHA-512, y la versión 1.1.1 de la API para almacenar directorios vacíos.
La cadena de la versión de la API como"1.0.0".
Ejemplo #1 Un ejemplo dePhar::apiVersion()
<?php
echoPhar::apiVersion();
?>El resultado del ejemplo sería:
1.1.1
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::buildFromDirectory—Construir un archivo phar desde los ficheros de un directorio
$base_dir,string$regex= ?):arrayNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Rellena un archivo phar con el contenido de un directorio. El segundo parámtro opcional es una expresión regular (pcre) que se utiliza para excluir ficheros. Cualquier nombre de fichero que coincida con la expresión regular será incluido, todos los demás serán excluidos. Para un control más exhaustivo, usePhar::buildFromIterator().
base_dirLa ruta completa o relativa al directorio que contiene todos los ficheros a añadir al archivo.
regexUna expresión regular de pcre opcional que se usa para filtrar la lista de ficheros. Solamente las rutas de fichero que coincidan con la expresión regular serán incluidas en el archivo.
Phar::buildFromDirectory()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no puede instanciar los iteradores intermos del directorio, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.
Ejemplo #1 Un ejemplo dePhar::buildFromDirectory()
<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
// añadir todos los ficheros del proyecto
$phar->buildFromDirectory(dirname(__FILE__) .'/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
$phar2= newPhar('proyecto2.phar',0,'proyecto2.phar');
// añadir todos los ficheros del, incluir solamente los ficheros php
$phar2->buildFromDirectory(dirname(__FILE__) .'/proyecto','/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::buildFromIterator—Construir un archivo phar desde un iterador
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Rellena un archivo phar desde un iterador. Están soportados dos estilos de iteradores, los iteradores que mapean el nombre de fichero dentro del phar al nombre del fichero en disco, y los iteradores como DirectoryIterator que devuelven objetos de la clase SplFileInfo. Se requiere el segundo parámetro para los iteradores que devuelven objetos de la clase SplFileInfo.
iterCualquier iterador que mapee de forma asociativa el fichero phar a la ubiciación o que devuelva objetos de la clase SplFileInfo
base_directoryPara los iteradores que devuelven objetos de la clase SplFileInfo, es la porción de cada ruta completa de fichero a eliminar cuando de añada al archivo phar
Phar::buildFromIterator()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.
Ejemplo #1 Un ejemplo dePhar::buildFromIterator()con SplFileInfo
Para la mayoría de los archivos tar/zip, el archivo reflejará la distribución real de directorios, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo phar que contenga los ficheros n esta distribución de muestra de directorios:
/ruta/al/proyecto/
config/
dist.xml
debug.xml
lib/
fichero1.php
fichero2.php
src/
procesa_algo.php
www/
index.php
cli/
index.phpEste código podría usarse para añadir estos ficheros al archivo phar "proyecto.phar":
<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
newRecursiveIteratorIterator(
newRecursiveDirectoryIterator('/ruta/al/proyecto')),
'/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>El fichero proyecto.phar se puede usar inmediatamente.Phar::buildFromIterator()no establece valores como la compresión y metainformación, que se puede hacer después de crear el archivo phar.
Como observación interesante,Phar::buildFromIterator()también se puede usar para copiar el contenido de un archivo phar existente, ya que los objetos de la clase Phar descienden de la claseDirectoryIterator:
<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
newRecursiveIteratorIterator(
newPhar('/ruta/a/otro_phar.phar')),
'phar:///ruta/a/otro_phar.phar/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>Ejemplo #2 Un ejemplo dePhar::buildFromIterator()con otros iteradores
La segunda forma de iterador se puede usar con cualquier iterador que devuelva un mapeo clave => valor, tal como un objeto de la claseArrayIterator:
<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
newArrayIterator(
array(
'fichero/interno.php'=>dirname(__FILE__) .'/algun_fichero.php',
'otro/fichero.jpg'=>fopen('/rota/a/archivo_grande.jpg','rb'),
)));
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>Este método lanza una excepción de tipoUnexpectedValueExceptioncuando el iterador devuelve valores incorrectos, tales como una clave de tipo integer en lugar de una cadena, una excepción de tipoBadMethodCallExceptioncuando se pasa un iterador basado en SplFileInfo sin un parámetrobase_directory, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::canCompress—Devuelve si la extensión phar soporta la compresión usando zlib o bzip2
$type= 0):boolEste método debería usarse para comprobar si es posible una compresicón antes de cargar un archivo phar que contiene ficheros comprimidos.
typeSe puede usar tantoPhar::GZoPhar::BZ2para comprobar si la compresión es posible con un algoritmo de compresión específico (zlib o bzip2).
truesi la compresión/descompresión está disponible,falsesi no.
Ejemplo #1 Un ejemplo dePhar::canCompress()
<?php
if (Phar::canCompress()) {
echofile_get_contents('phar://phar_comprimido.phar/fichero/interno.txt');
} else {
echo'La compresión no está disponible';
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::canWrite—Devolver si la extensión phar soporta la escritura y creación de archivos phar
Este método estático determina si ha sido deshabilitado el acceso a escritura en el php.ini del sistema mediante la variable INIphar.readonly.
truesi el acceso a escritura esta habilitado,falsesi está deshabilitado.
Ejemplo #1 Un ejemplo dePhar::canWrite()
<?php
if (Phar::canWrite()) {
file_put_contents('phar://miphar.phar/fichero.txt','hola, qué tal');
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::compress—Comprimir el archivo Phar entero usando la compresión Gzip o Bzip2
$compression,string$extension= ?):objectNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Para archivos phar basados en tar y en phar, este método comprime el archivo entero usando la compresión gzip o bzip2. El fichero resultante puede ser procesado con el comando gunzip/bunzip, o se puede acceder a él directa y transparentemente con la extensión Phar.
Para archivos phar basados en Zip, este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para poder comprimir con la compresión gzip, y la extensiónbzip2debe estar habilitada para poder comprimir con la compresión bzip2. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.
Además, este método renombra automáticamente el archivo, añadiéndole.gz,.bz2o eliminado la extensión si se pasaPhar::NONEpara eliminar la compresión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.
compressionLa compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.
extensionPor omisión, la extensión es.phar.gzo.phar.bz2para comprimir archivos phar, y.phar.tar.gzo.phar.tar.bz2para comprimir archivos tar. Para la descompresión, las extensiones de fichero predeterminadas son.phary.phar.tar.
Devuelve un objeto de la clasePhar.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePhar::compress()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero1.txt'] ='hola';
$p['mifichero12.txt'] ='hola';
$p1=$p->compress(Phar::GZ);// copia a /ruta/a/mi.phar.gz
$p2=$p->compress(Phar::BZ2);// copia a /ruta/a/mi.phar.bz2
$p3=$p2->compress(Phar::NONE);// excepción: /ruta/a/mi.phar ya existe
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::compressFiles—Comprime todos los ficheros del archivo Phar actual
$compression):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Para archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.
Para achivos phar basados en Zip y phar, este método comprime todos los ficheros del archivo Phar usando la compresión especificada. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica. Además, si cualquier fichero ya está comprimido con la compresión bzip2/zlib, la extensión respectiva debe estar habilitada para poder descomprimir los ficheros antes de re-comprimirlos. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.
compressionLa compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.
No devuelve ningún valor.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePhar::compressFiles()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>El resultado del ejemplo sería:
string(13) "mifichero.txt" bool(false) bool(false) bool(false) string(14) "mifichero2.txt" bool(false) bool(false) bool(false) string(13) "mifichero.txt" int(4096) bool(false) bool(true) string(14) "mifichero2.txt" int(4096) bool(false) bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::__construct—Construir un objeto de archivo Phar
$fname,int$flags= ?,string$alias= ?)fnameRuta a un archivo Phar existente o para ser creado La extensión del nombre del fichero debe contener .phar.
flagsBanderas a pasar a la clase padreRecursiveDirectoryIterator.
aliasAlias con el que referirse al archivo Phar en las llamadas a funcionalidades de flujos.
Lanza una excepción de tipoBadMethodCallExceptionsi se llama dos veces, o una excepción de tipoUnexpectedValueExceptionsi no se puede abrir el archivo phar.
Ejemplo #1 Un ejemplo dePhar::__construct()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',FilesystemIterator::CURRENT_AS_FILEINFO|FilesystemIterator::KEY_AS_FILENAME,
'mi.phar');
} catch (UnexpectedValueException $e) {
die('No se pudo abrir mi.phar');
} catch (BadMethodCallException $e) {
echo'Técnicamente esto no puede suceder';
}
// esto funciona ahora
echofile_get_contents('phar://mi.phar/ejemplo.txt');
// y funciona si hemos escrito
echofile_get_contents('phar:///ruta/a/mi.phar/ejemplo.txt');
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::convertToData—Convertir un archivo phar en un fichero tar o zip no ejecutable
$format= 9021976,int$compression= 9021976,string$extension= ?):PharDataEste método se usa para convertir un archivo phar ejecutable en un fichero tar o zip. Para hacer del tar o zip un fichero no ejecutable, se eliminan los ficheros del phar de rutina de interoperabilidad y de alias del recién creado nuevo archivo.
Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallExceptionsi el archivo está en el formato de fichero phar. Para archivos en el formato tar o zip, este método convierte el archivo en un archivo no ejecutable.
En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.
formatEste parámetro debería serPhar::TARoPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.
compressionEste parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.
extensionEste parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que.pharno puede ser usado en ningún lugar del nombre de fichero de un archivo tar o zip no ejecutable.
Si se convierte a un archivo basado en tar, las extensiones predeterminadas son.tar,.tar.gz, y.tar.bz2dependiendo de la compresión especificada. Para archivos basados en zip, la extensión predetermianda es.zip.
El método devuelve un objetoPharDataen caso de éxito, y lanza una excepción en caso de error.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.
Ejemplo #1 Un ejemplo dePhar::convertToData()
Utilizar Phar::convertToData():
<?php
try {
$tarphar= newPhar('miphar.phar.tar');
// observe que miphar.phar.tar *no* está desvinculado.
// convertirlo a un formato de fichero tar no ejecutable,
// se crea miphar.tar
$tar=$tarphar->convertToData();
// convertirlo a un formato zip no ejecutable, se crea miphar.zip
$zip=$tarphar->convertToData(Phar::ZIP);
// crear miphar.tbz
$tgz=$tarphar->convertToData(Phar::TAR,Phar::BZ2,'.tbz');
// crear miphar.phar.tgz
$phar=$tarphar->convertToData(Phar::PHAR);// lanza una excepción
} catch (Exception $e) {
// manejar el error aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::convertToExecutable—Convertir un archivo phar en otro formato de archivo phar ejecutable
$format= 9021976,int$compression= 9021976,string$extension= ?):PharNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Este método se utiliza para convertir un archivo phar en otro formato de fichero. Por ejemplo, se puede utilizar para crear un archivo phar ejecutable basado en tar desde un archivo phar ejecutable basado en zip, o desde un archivo phar ejecutable en el formato de fichero phar. Además, se puede utilizar para aplicar la compresión al archivo completo a un archivo basado en phar o tar.
Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallException
En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.
formatEste parámetro debería serPhar::PHAR,Phar::TAR, oPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.
compressionEste parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.
extensionEste parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que todos los archivos phar basados en zip o en tar deben contener.pharen su extensión de fichero para poder ser procesados como un archivo phar.
Si se convierte a un archivo basado en phar, las extensiones predeterminadas son.phar,.phar.gz, o.phar.bz2dependiendo de la compresión especificada. Para archivos phar basados en tar, las extensiones predeterminadas son.phar.tar,.phar.tar.gz, y.phar.tar.bz2. Para archivos phar basados en zip, la estensión predeterminada es.phar.zip.
El método devuelve un objetoPharen caso de éxito, y lanza una excepción en caso de error.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), una excepción de tipoUnexpectedValueExceptionsi el soporte para escritura está deshabilitado, y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.
Ejemplo #1 Un ejemplo dePhar::convertToExecutable()
Utilizar Phar::convertToExecutable():
<?php
try {
$tarphar= newPhar('miphar.phar.tar');
// convertirlo al formato de fichero phar
// observe que miphar.phar.tar *no* está desvinculado
$phar=$tarphar->convertToExecutable(Phar::PHAR);// crea miphar.phar
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
// crea miphar.phar.tgz
$comprimido=$phar->convertToExecutable(Phar::TAR,Phar::GZ,'.phar.tgz');
} catch (Exception $e) {
// manejar el error aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::copy—Copiar un fichero interno de un archivo phar a otro fichero nuevo dentro del phar
$oldfile,string$newfile):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Copia un fichero interno de un archivo phar a otro fichero nuevo dentro del phar. Esta es una alternativa orientada a objetos para usarcopy()con la envoltura de flujos phar.
oldfilenewfileDevuelvetrueen caso de éxito, pero es más seguro encerrar la llamada al método en un bloque try/catch y asumir el éxito si no se lanza ninguna excepción.
Lanza una excepción de tipoUnexpectedValueExceptionsi el fichero origen no exite, el fichero destino ya existe, el acceso a escritura está deshabilitado, la apertura de cualquiera de los dos ficheros falla, la lectura del fichero fuente falla, o una excepción de tipoPharExceptionsi la escritura de los cambios del phar falla.
Ejemplo #1 Un ejemplo dePhar::copy()
Este ejemplo muestra el uso dePhar::copy()y su equivalente con envoltura de flujos. La principal diferencia entre los dos enfoques es el manejo de errores. Todos los métodos de Phar lanzan excepciones, mientras que la envoltura de flujos utilizatrigger_error().
<?php
try {
$phar= newPhar('miphar.phar');
$phar['a'] ='hola';
$phar->copy('a','b');
echo$phar['b'];// imprime "hola"
} catch (Exception $e) {
// manejar errores
}
// el equivalente con envoltura de flujos del código de arriba.
// Se dispara E_WARNINGS en caso de error en vez de excepciones.
copy('phar://miphar.phar/a','phar//miphar.phar/c');
echofile_get_contents('phar://miphar.phar/c');// imprimie "hola"
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::count—Devuelve el número de entradas (ficheros) en el archivo Phar
El número de archivos que contiene Phar, o0(el número cero) si no contiene.
Ejemplo #1Phar::count()ejemplo
<?php
// asegurarse de que no existe
@unlink('brandnewphar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/brandnewphar.phar',0,'brandnewphar.phar');
} catch (Exception $e) {
echo'No se pudo crear Phar:',$e;
}
echo'El nuevo Phar tiene '.$p->count() ." entradas\n";
$p['file.txt'] ='hi';
echo'El nuevo Phar tiene '.$p->count() ." entradas\n";
?>El resultado del ejemplo sería:
El nuevo Phar tiene 0 entradas El nuevo Phar tiene 1 entradas
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::createDefaultStub—Crear una rutina de interoperabilidad específica del formato de fichero phar
$indexfile= ?,string$webindexfile= ?):stringEste método está destinado a la creación de rutinas de interoperabilidad (stubs) específicas del formato de fichero phar, y no está destinado a ustilizarlo con archivo phar basados en tar o zip.
Los archivos Phar contienen una rutina de interoperabilidad cargadora (en inglésstub) escrita en PHP que se ejecuta cuando el archivo es ejecutado en el propio PHP mediante inclusión:
<?php
include'miphar.phar';
?>
php miphar.phar
Este método proporciona una manera simple y sencilla de crear una rutina de interoperabilidad que ejecutará un fichero inicial desde el archivo phar. Además, se pueden especificar diferentes ficheros para ejecutar el archivo phar desde la línea de comandos o a través de un servidor web. La rutina de interoperabilidad cargadora también llama aPhar::interceptFileFuncs()para permitir empaquetar de manera sencilla una aplicación PHP que accede al sistema de ficheros. Si la extensión phar no está presente, la rutina de interoperabilidad cargadora extraerá el archivo phar en un directorio temporal y después operará sobre los archivos. Una función d cierre borra los ficheros temporales a la salida.
Devuelve una cadena que contiene una rutina de interoperabildad personalizada (stub) que permite al archivo Phar creado funcionar con o sin la extensón Phar habilitada.
Lanza una excepción de tipoUnexpectedValueExceptionsi cualquier parámetro es mayor de 400 bytes.
Ejemplo #1 Un ejemplo dePhar::createDefaultStub()
<?php
try {
$phar= newPhar('miphar.phar');
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::decompress—Descomprimir un archivo Phar entero
$extension= ?):objectNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Para archivos phar basados en tar y phar, este método descomprime el archivo entero.
Para archivos phar basados en Zip, este método este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para descomprimir un archivo comprimido con la compresión gzip, y la extensiónbzip2debe estar habilitada para descomprimir un archivo comprimido con la compresión bzip2. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.
Además, este método cambia automáticamente la extensión del archivo,.pharpor omisión para archivos phar, o.phar.tarpara archivos phar basados en tar. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.
extensionPara la descompresión, las extensiones de fichero predeterminadas son.phary.phar.tar. Use este parámetro para especificar otra extensión de fichero. Observe que todos los archivos phar ejecutables deben contener.pharen su nombre de fichero.
Devuelve un objeto de la clasePhar.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePhar::decompress()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar.gz');
$p['mifichero1.txt'] ='hola';
$p['mifichero12.txt'] ='hola';
$p3=$p2->decompress();// crea /ruta/a/mi.phar
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::decompressFiles—Descomprimir todos los ficheros del archivo Phar actual
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Para archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.
Para achivos phar basados en Zip y phar, este método descomprime todos los ficheros del archivo Phar. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica si cualquier fichero está comprimido con la compresión bzip2/zlib. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePhar::decompressFiles()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p->compressFiles(Phar::GZ);
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>El resultado del ejemplo sería:
string(13) "mifichero.txt" int(4096) bool(false) bool(true) string(14) "mifichero2.txt" int(4096) bool(false) bool(true) string(13) "mifichero.txt" bool(false) bool(false) bool(false) string(14) "mifichero2.txt" bool(false) bool(false) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
Phar::delMetadata—Eliminar la metainformación global del phar
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Elimina la metainformación global del phar
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::delMetaData()
<?php
try {
$phar= newPhar('miphar.phar');
var_dump($phar->getMetadata());
$phar->setMetadata("hola, qué tal");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// manejar errores
}
?>El resultado del ejemplo sería:
NULL string(14) "hola, qué tal" NULL
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::delete—Borrar un fichero dentro de un archivo phar
$entry):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Borra un fichero dentro de un archivo. Esto es el equivalente funcional de llamar aunlink()en el equivalente de envoltura de flujos, tal como se muestra en el ejemplo de abajo.
entryLa ruta dentro de un archivo para borrar el fichero.
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi se produjo algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::delete()
<?php
try {
$phar= newPhar('miphar.phar');
$phar->delete('desvincular/yo.php');
// esto es equivalente a:
unlink('phar://miphar.phar/desvincular/yo.php');
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::__destruct—Destructs a Phar archive object
Esta función no tiene parámetros.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::extractTo—Extraer el contenido de un archivo phar a un directorio
$pathto,string|array$files= ?,bool$overwrite= false):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Extrae todos los ficheros de un archivo phar al disco. Los ficheros y directorios extraídos conservan los mismos permisos que los almacenados en el archivo. Los parámetros opcionales permiten controlar qué ficheros serán extraídos, y si los ficheros existentes en disco podrán ser sobrescritos. El segundo parámetrofilespuede ser el nombre de un fichero o directorio a extraer, o un array de nombre de ficheros y directorios a extraer. Por omisión, este método no sobrescribirá los ficheros existentes, aunque el tercer parámetro se puede establecer a true para habilitar la sobrescritura de ficheros. Este método es similar aZipArchive::extractTo().
pathtoRuta dentro de un archivo al fichero a borrar.
filesEl nombre de un fichero o directorio a extraer, o un array de ficheros/directorios a extraer.
overwriteEsteblecer atruepara habilitar la sobrescritura de ficheros existentes
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::extractTo()
<?php
try {
$phar= newPhar('miphar.phar');
$phar->extractTo('/ruta/completa');// extraer todos los ficheros
$phar->extractTo('/otra/ruta','fichero.txt');// extraer solamente fichero.txt
$phar->extractTo('/esta/ruta',
array('fichero1.txt','fichero2.txt'));// extraer solamente 2 ficheros
$phar->extractTo('/tercera/ruta',null,true);// extraer todos los ficheros y sobrescribirlos
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)
Phar::getAlias—Get the alias for Phar
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
Returns the alias ornullif there's no alias.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::getMetadata—Devolver la metainformación de un archivo phar
Recupera la información de un archivo. La metainformación puede ser cualquier variable de PHP que pueda ser serializada.
No tiene parámetros.
Cualquier variable de PHP que pueda ser serializada y almacenada como metainformación del archivo Phar, onullsi no hay metainformación almacenada.
Ejemplo #1 Un ejemplo dePhar::getMetadata()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola";';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo'No se pudo crear y/o modificar el phar:',$e;
}
?>El resultado del ejemplo sería:
array(1) {
["bootstrap"]=>
string(11) "fichero.php"
}
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::getModified—Devolver si el phar fue modificado
Este método se puede usar para determinar si un phar tiene un fichero interno eliminado, o el contenido de un fichero ha cambiado de alguna forma.
No tiene parámetros.
truesi el phar ha sido modificado desde su apertura,falsesi no.
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
Phar::getPath—Get the real path to the Phar archive on disk
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::getSignature—Devolver la firma MD5/SHA1/SHA256/SHA512/OpenSSL de un archivo Phar
Devuelve la firma de verificación de un archivo phar en una cadena hexadecimal.
Un array con las firmas del archivo abierto en la clavehash, yMD5,SHA-1,SHA-256,SHA-512, oOpenSSLen la clavehash_type. Esta firma es un hash calculado sobre el contenido entero del phar, y puede ser usada para verificar la integridad del archivo. Se requiere absolutamente una firma válida de todos los archivos phar ejecutables si la variable INIphar.require_hashestá establecida a true.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::getStub—Devolver el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
Los archivos Phar contienen una rutina de interoperabilidad cargadora (en inglésstub) escrita en PHP que se ejecuta cuando el archivo es ejecutado en el propio PHP mediante inclusión:
<?php
include'myphar.phar';
?>
php myphar.phar
Devuelve una cadena que contiene la rutina de interoperabilidad cargadora (stub) del archivo Phar actual.
Lanza una excepción de tipoRuntimeExceptionsi no es posible leer la rutina de interoperabilidad del archivo Phar.
Ejemplo #1 Un ejemplo dePhar::getStub()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
echo$p->getStub();
echo"==NEXT==\n";
$p->setStub("<?php
function __autoload($clase)
{
include 'phar://' . str_replace('_', '/',$clase);
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/arrancar.php';
__HALT_COMPILER(); ?>");
echo$p->getStub();
?>El resultado del ejemplo sería:
<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($clase)
{
include 'phar://' . str_replace('_', '/', $clase);
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/arrancar.php';
__HALT_COMPILER(); ?>
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
Phar::getSupportedCompression—Devolver un array de los algoritmos de compresión soportados
No tiene parámetros.
Devuelve un array que contienePhar::GZoPhar::BZ2, dependiendo de la disponibilidad de la extensiónzlibo de la extensiónbz2.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)
Phar::getSupportedSignatures—Devolver un array con los tipos de firmas soportados
Devuelve un array con los tipos de firmas soportados
No tiene parámetros.
Devuelve un array que contiene cualquiera de las firmasMD5,SHA-1,SHA-256,SHA-512, oOpenSSL.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::getVersion—Devolver información de la versión del archivo Phar
Devuelve la versión de la API de un archvo Phar abierto.
La versión de la API del arcivo abierto. No se debe confundir con la versión de la API que la extensión phar cargada usará para crear nuevos phars. Cada archivo Phar tiene la versión de la API codificada dentro de su manifiesto. Véase la documentación delformato de fichero Pharpara más información.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
Phar::hasMetadata—Devolver si el phar tiene metainformación global
Devuelve si el phar tiene metainformación global establecida.
No tiene parámetros.
Devuelvetruesi la metainformación ha sido establecida, yfalsesi no.
Ejemplo #1 Un ejemplo dePhar::hasMetadata()
<?php
try {
$phar= newPhar('miphar.phar');
var_dump($phar->hasMetadata());
$phar->setMetadata(array('cosa'=>'hola'));
var_dump($phar->hasMetadata());
$phar->delMetadata();
var_dump($phar->hasMetadata());
} catch (Exception $e) {
// manejar errores
}
?>El resultado del ejemplo sería:
bool(false) bool(true) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::interceptFileFuncs—Ordenar a phar interceptar fopen, file_get_contents, opendir, y todas las funciones relacionadas con estadísticas
Ordena a phar interceptarfopen(),readfile(),file_get_contents(),opendir(), y todas las funciones relacionadas con estadísticas. Si cualquiera de estas tres funciones es llamada desde dentro de un archivo phar con una ruta relativa, la llamada es modificada para acceder al fichero dentro del archivo phar. Se asume que las rutas absolutas son intentos para cargar ficheros externos desde el sistema de ficheros.
Esta función hace posible ejecutar aplicaciones de PHP diseñadas para ejecutarse desde un disco duro como una aplicación phar.
No tiene parámetros.
Ejemplo #1 Un ejemplo dePhar::interceptFileFuncs()
<?php
Phar::interceptFileFuncs();
include'phar://'.__FILE__.'/fichero.php';
?>Se asume que este phar está en/ruta/a/miphar.phary que contienefichero.phpyfichero2.txt, sifichero.phpcontiene este código:
Ejemplo #2 Un ejemplo dePhar::interceptFileFuncs()
<?php
echofile_get_contents('fichero2.txt');
?>Normalmente, PHP buscaráfichero2.txten el directorio actual, que traducirá como el directorio del fichero.php, o el direcotorio actual de un usuario de la línea de comandos. En el código del ejemplo anterior,Phar::interceptFileFuncs()ordena a PHP que considere el directorio actual comophar:///ruta/a/miphar.phar/y por lo tanto abraphar:///ruta/a/miphar.phar/fichero2.txt.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::isBuffering—Determinar si las operaciones de escritura de Phar está siendo almacenadas en buffer, o están siendo volcadas directamente al disco
Este método se puede usar para determinar si un Phar guardará los cambios al disco inmediatamente, o si se necesita una llamadaPhar::stopBuffering()para habilitar el guardado de los cambios.
La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.
Devuelvetruesi las operaciones de escritura están siendo almacenadas en buffer,falsesi no.
Ejemplo #1 Un ejemplo dePhar::isBuffering()
<?php
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p2= newPhar('phar_existente.phar');
$p['fichero1.txt'] ='hola';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>El resultado del ejemplo sería:
bool(false) bool(false) =2= bool(true) bool(false) =3= bool(false) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::isCompressed—Devuelve Phar::GZ oPHAR::BZ2 si el archivo phar entero está comprimido (.tar.gz/tar.bz, etc.)
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Devuelve Phar::GZ o PHAR::BZ2 si el archivo phar entero está comprimido (.tar.gz/tar.bz, etc.). Los archivos phar basados en Zip no pueden ser comprimidos como un fichero, y por lo tanto, este método devolverá siemprefalsesi se requiere un archivo phar basado en zip.
No tiene parámetros.
Phar::GZ,Phar::BZ2ofalse
Ejemplo #1 Un ejemplo dePhar::isCompressed()
<?php
try {
$phar1= newPhar('miphar.zip.phar');
var_dump($phar1->isCompressed());
$phar2= newPhar('sin_comprimir.tar.phar');
var_dump($phar2->isCompressed());
$phar2->compress(Phar::GZ);
var_dump($phar2->isCompressed() ==Phar::GZ);
} catch (Exception $e) {
}
?>El resultado del ejemplo sería:
bool(false) bool(false) bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::isFileFormat—Devolver true si el archivo phar está basado en el formato de fichero tar/phar/zip dependiendo del parámetro
$format):boolformatPhar::PHAR,Phar::TAR, oPhar::ZIPpara comprobar el formato del archivo.
Devuelvetruesi el archivo phar coincide con el formato de fichero solicitado por el parámetro
Se lanza una excepción de tipoPharExceptionsi el parámetro es un especificador de formato de fichero desconocido.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
Phar::isValidPharFilename—Devolver si el nombre de fichero dado es un nombre de fichero phar válido
$filename,bool$executable= true):boolDevuelve si el nombre de fichero dado es un nombre de fichero phar válido que será reconocido como un archivo phar por la extensión phar. Este método se puede usar para comprobar un nombre sin tener que instanciar un archivo phar y capturar la inevitable excepción que será lanzada si se especifica un nombre no válido.
filenameEl nombre o la ruta completa al archivo phar aún no creado
executableEste parámetro determina si el nombre de fichero debería ser tratado como un archivo phar ejecutable o un archivo de datos no ejecutable
Devuelvetruesi el nombre de fichero es válido,falsesi no.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::isWritable—Devolver si el archivo phar se puede modificar
Este método devuelvetruesiphar.readonlyes0, y el archivo phar real del disco no es de sólo lectura.
No tiene parámetros.
Devuelvetruesi el archivo phar puede ser modificado
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::loadPhar—Cargar cualquier archivo phar con un alias
$filename,string$alias= ?):boolEste método se puede usar para leer el contenido de una archivo Phar externo. Esto es más útil para asignar un alias a un phar, por lo que las referencias subsiguientes al phar puedan usar el alias más corto, o para cargar archivos Phar que contengan solamente datos y no estén concebidos para la ejecución/inclusión en scripts de PHP.
filenameLa ruta completa o relativa al archivo phar a abrir
aliasEl alias que puede usarse para referirse al archivo phar. Observe que muchos archivos phar especifican un alias explícito dentro del archivo phar, y que una excepción de tipoPharExceptionserá lanzada si en este caso se especifica un nuevo alias.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoPharExceptionsi se pasa un alias y en archivo phat ya tiene uno explícito
Ejemplo #1 Un ejemplo dePhar::loadPhar()
Phar::loadPhar puede usarse en cualquier lugar para cargar un archivo Phar externo, mientras que Phar::mapPhar debería usarse en una rutina de interoperabilidad cargadora para un Phar.
<?php
try {
Phar::loadPhar('/ruta/a/phar.phar','mi.phar');
echofile_get_contents('phar://mi.phar/fichero.txt');
} catch (PharException $e) {
echo$e;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::mapPhar—Leer el fichero (un phar) que está en ejecución y registrar su manifiesto
$alias= ?,int$dataoffset= 0):boolEste método estático solamente se puede usar dentro de una rutina de interoperabilidad cargadora de un archivo Phar para inicializar el phar cuando sea directamente ejecutado, o cuando se incluya en otro scrip.
aliasEl alias que puede usarse en las URLphar://para referirse a este archivo, en vez de su ruta completa.
dataoffsetVariable sin uso, está aquí por compatibilidad con los PHP_Archive de PEAR.
Devuelvetrueen caso de éxito ofalseen caso de error.
Se lanza una excepción de tipoPharExceptionsi no se llama directamente dentro de la ejecución de PHP, si no se encuentra el token __HALT_COMPILER(); en el fichero fuente actual, o si el fichero no se puede abrir para lectura.
Ejemplo #1 Un ejemplo dePhar::mapPhar()
mapPhar debería usarse dentro de una rutina de interoperabilidad cargadora de phar. Utilice loadPhar para cargar un phar externo en memoria.
Aquí está una rutina de interoperabilidad de Phar de muestra que usa mapPhar.
<?php
function__autoload($clase)
{
include'phar://mi.phar/'.str_replace('_','/',$clase) .'.php';
}
try {
Phar::mapPhar('mi.phar');
include'phar://mi.phar/inicio.php';
} catch (PharException $e) {
echo$e->getMessage();
die('No se puede inicializar el Phar');
}
__HALT_COMPILER();(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::mount—Montar un fichero o ruta externos en una ubicación virtual dentro de un archivo phar
$pharpath,string$externalpath):voidAl igual que con el concepto del sistema de ficheros de Unix de montar dispositivos externos en rutas dentro del árbol de directorios,Phar::mount()siempre se refiere a ficheros y directorios externos como si estuvieran dentro de un archivo phar. Esto perimte una potente abstracción tal como referirse a ficheros de configuración externos como si estuvieran dentro del archivo.
pharpathLa ruta interna a usar dentro del archivo phar como la ubicación de la ruta montada. Debe ser una ruta relativa dentro del archivo phar, y no debe existir.
externalpathUna ruta o un URL a un fichero o directorio externo a montar dentro del archivo phar.
No devuelve nada. Lanza una excepción de tipoPharExceptionen caso de fallo.
Lanza una excepción de tipoPharExceptionsi ocurrió algún problema al montar la ruta.
Ejemplo #1 Un ejemplo dePhar::mount()
El siguiente ejemplo muestra el acceso a un fichero de configuración externo como si fuera una ruta dentro de un archivo phar.
Lo primero, el código dentro de un archivo phar:
<?php
$configuración=simplexml_load_string(file_get_contents(
Phar::running(false) .'/config.xml'));
?>Lo siguiente, el código externo utilizado para montar el fichero de configuración:
<?php
// primero se establece la asociación entre el config.xml abstracto
// y el real del disco
Phar::mount('phar://config.xml','/home/example/config.xml');
// ahora ejecutar la aplicación
include'/ruta/a/archivo.phar';
?>Otro método es poner el codigo de montaje dentro de la rutina de interoperabilidad del archivo phar. Aquí está un ejemplo de establecer un fichero de configuración predeterminado si no se especifica una configuración de usuario:
<?php
// primero se establece la asociación entre el config.xml abstracto
// y el real del disco
if (defined('EXTERNAL_CONFIG')) {
Phar::mount('config.xml',EXTERNAL_CONFIG);
if (file_exists(__DIR__.'/extra_config.xml')) {
Phar::mount('extra.xml',__DIR__.'/extra_config.xml');
}
} else {
Phar::mount('config.xml','phar://'.__FILE__.'/default_config.xml');
Phar::mount('extra.xml','phar://'.__FILE__.'/default_extra.xml');
}
// ahora ejecutar la aplicación
include'phar://'.__FILE__.'/index.php';
__HALT_COMPILER();
?>...y el código externo para cargar este archivo phar:
<?php
define('EXTERNAL_CONFIG','/inicio/ejemplo/config.xml');
// ahora ejecutar la aplicación
include'/ruta/a/archivo.phar';
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::mungServer—Definir una lista de hasta 4 variables $_SERVER que debería ser modificadas para la ejecución
$munglist):voidPhar::mungServer()solamente debería ser llamado dentro de la rutina de interoperabilidad de un archivo phar.
Define una lista de hasta 4 variables$_SERVERque deberían ser modificadas para la ejecución. Las variables que pueden ser modificadas para eliminar rastros de una ejecución de un phar sonREQUEST_URI,PHP_SELF,SCRIPT_NAMEySCRIPT_FILENAME.
Por sí solo, este método no hace nada. Solamente al combinarlo conPhar::webPhar()hace que tenga efecto, y sólo cuando el fichero solicitado es un fichero de PHP a ser procesado. Observe que las variablesPATH_INFOyPATH_TRANSLATEDson siempre modificadas.
Los valores originales de las variables que son modificadas son almacenados en el array SERVER con el prefijoPHAR_, así por ejemploSCRIPT_NAMEsería guardado comoPHAR_SCRIPT_NAME.
munglistUn array que contiene como índices de cadenasREQUEST_URI,PHP_SELF,SCRIPT_NAMEySCRIPT_FILENAME. Otros valores lanzan una excepción, yPhar::mungServer()es sensible a mayúsculas-minúsculas.
No devuelve nada.
Lanza una excepción de tipoUnexpectedValueExceptionsi se encontró algún problema con la información pasada.
Ejemplo #1 Un ejemplo dePhar::mungServer()
<?php
// rutina de interoperabilidad de ejemplo
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::offsetExists—Determina si un fichero existe en un phar
$offset):boolÉsta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array.
offsetExists() es llamado siempre queisset()sea llamada.
offsetEl nombre del fichero (ruta relativa) a buscar en un Phar.
Devuelvetruesi el fichero existe dentro del phar, ofalsesi no.
Ejemplo #1 Un ejemplo dePhar::offsetExists()
<?php
$p= newPhar(dirname(__FILE__) .'/mi.phar',0,'mi.phar');
$p['primer_fichero.txt'] ='primer fichero';
$p['segundo_fichero.txt'] ='segundo_fichero';
// las siguientes líneas llama a offsetExists() indirectamente
var_dump(isset($p['primer_fichero.txt']));
var_dump(isset($p['no_existe.txt']));
?>El resultado del ejemplo sería:
bool(true) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::offsetGet—Obtener un objeto de la clasePharFileInfopara un fichero específico
$offset):intÉsta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array.Phar::offsetGet()se usa para recuperar ficheros de un archivo Phar.
offsetEl nombre del fichero (ruta relativa) a buscar en un Phar.
Devuelve un objeto de la clasePharFileInfoque puede usarse para iterar sobre el contenido de un fichero o para recuperar información sobre el fichero actual.
Este método lanza una extepción de tipoBadMethodCallExceptionsi el fichero no existe en el archivo Phar.
Ejemplo #1 Ejemplo dePhar::offsetGet()
Ya que todas las clases implementan la iterfazArrayAccess,Phar::offsetGet()es automáticamente llamada a utilizar el operador[].
<?php
$p= newPhar(dirname(__FILE__) .'/miphar.phar',0,'miphar.phar');
$p['existe.txt'] ="el fichero existe\n";
try {
// automáticamente llama a offsetGet()
echo$p['existe.txt'];
echo$p['no_existe.txt'];
} catch (BadMethodCallException $e) {
echo$e;
}
?>El resultado del ejemplo sería:
el fichero existe Entry no_existe.txt does not exist
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::offsetSet—Establecer el contenido de un fichero interno a aquel de un fichero externo
$offset,string$value):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetSet se utiliza para modificar un fichero existente, o añadir un nuevo fichero al archivo Phar.
offsetEl nombre del fichero (ruta relativa) a modificar en un Phar.
valueEl contenido del fichero.
No devuelve ningún valor.
Siphar.readonlyes1, lanza una excepción de tipoBadMethodCallException, ya que modificar un Phar sólo está permitido cuando phar.readonly está establecido a0. Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo Phar al disco.
Ejemplo #1 Un ejemplo dePhar::offsetSet()
No se debería acceder directamente a offsetSet, en su lugar se utiliza el operador[]para acceder al array.
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
try {
// llama a offsetSet
$p['fichero.txt'] ='Hola qué tal';
} catch (Exception $e) {
echo'No se pudo modificar fichero.txt:',$e;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::offsetUnset—Eliminar un fichero de un phar
$offset):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetUnset se utiliza para borrar un fichero existente, y es llamado por el constructor de lenguajeunset().
offsetEl nombre del fichero (ruta relativa) a eliminar en un Phar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Siphar.readonlyes1, lanza una excepción de tipoBadMethodCallException, ya que modificar un Phar sólo está permitido cuando phar.readonly está establecido a0. Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo Phar al disco.
Ejemplo #1 Un ejemplo dePhar::offsetUnset()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
try {
// borra fichero.txt de mi.phar llamando a offsetUnset
unset($p['fichero.txt']);
} catch (Exception $e) {
echo'No se pudo borrar fichero.txt: ',$e;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::running—Devolover la ruta completa del disco o el URL completo de phar del archivo Phar que está en ejecución
$retphar= true):stringDevuelve la ruta completa del archivo phar en ejecución. Este método tiene la intención de utilizarse como la constante mágica__FILE__, y solamente tiene efecto dentro de un archivo phar en ejecución.
Dentro de una rutina de interoperabilidad de un archivo,Phar::running()devuelve"". Use simplemente__FILE__para acceder al phar que está ejecutándose acualmente dentro de una rutina de interoperabilidad.
retpharSi esfalse, se devuelve la ruta completa del disco del archivo phar. Si estrue, se devuelve el URL phar completo.
Devuelve el nombre de fichero si es válido, si no una cadena vacía.
Ejemplo #1 Un ejemplo dePhar::running()
Para el siguiente ejemplo se asume que el archivo phar está ubicado en/ruta/a/phar/mi.phar.
<?php
$a=Phar::running();// $a es "phar:///ruta/a/mi.phar"
$b=Phar::running(false);// $b es "/ruta/a/mi.phar"
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)
Phar::setAlias—Establecer el alias para un archivo Phar
$alias):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Establece el alias par un archivo Phar, y lo escribe como el alias permanente para este archivo phar. Un alias puede usarse internamente a un archivo phar para asegurarse de que el uso de la envoltura de flujopharpara acceder a ficheros internos, siempre funcione sin tener en cuenta la ubicación del archivo phar en el sistema de ficheros. Otra alternativa es confiar en la intercepción de Phar deincludeo utilizarPhar::interceptFileFuncs()y usar rutas relativas.
aliasUna cadena abreviada para referirse a este archivo en el acceso con la envoltura de flujophar.
Lanza una excepción de tipoUnexpectedValueExceptioncuando el acceso a escritura está deshabilitado, y una excepción de tipoPharExceptionsi el alias ya está en uso o se encontró algún problema al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::setAlias()
<?php
try {
$phar= newPhar('miphar.phar');
$phar->setAlias('mip.phar');
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::setDefaultStub—Establecer el cargador o la rutina de interoperabilidad de un archivo Phar al cargador predeterminado
$index= ?,string$webindex= ?):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Este método es un método cómodo que combina la funcionalidad dePhar::createDefaultStub()yPhar::setStub().
indexLa ruta relativa dentro del archivo phar a ejectuar si se accede desde la línea de comandos
webindexLa ruta relativa dentro del archivo phar a ejectuar si se accede desde un servidor web
Devuelvetrueen caso de éxito ofalseen caso de error.
Se lanza una excepción de tipoUnexpectedValueExceptionsiphar.readonlyestá habilitado en php.ini. Se lanza una excepción de tipoPharExceptionsi se encuentra cualquier problema al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::setDefaultStub()
<?php
try {
$phar= newPhar('miphar.phar');
$phar->setDefaultStub('cli.php','web/index.php');
// esto es lo mismo que:
// $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::setMetadata—Establecer la metainformación de un archivo phar
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Phar::setMetadata()debería usarse para almacenar información personalizada que describa algo sobre el archivo phar como una entidad completa.PharFileInfo::setMetadata()debería usarse para metainformación específica de cada fichero. La metainformación puede ralentizar la velocidad de carga de un archivo phar si la información es grande.
Algunos posibles usos para la metainformación incluyen especificar qué fichero dentro del archivo debería usarse para cargar el archivo, o la ubicación de un fichero de manifiesto como el fichero package.xml de» PEAR. Sin embargo, se puede almacenar cualquier información útil que describa el archivo phar.
metadataCualquier variable de PHP que contenga la información a almacenar que describa el archivo phar
No devuelve ningún valor.
Ejemplo #1 Un ejemplo dePhar::setMetadata()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola"';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo'No se pudo crear y/o modificar el phar:',$e;
}
?>El resultado del ejemplo sería:
array(1) {
["bootstrap"]=>
string(11) "fichero.php"
}
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm—Establecer el algoritmo de firma para un phar y aplicarlo
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Establece el algoritmo de firma para un phar y lo aplica. El algoritmo de firma debe ser una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL.
Observe que todos los archivos phar ejecutables tienen una firma creada automáticamente,SHA1por omisión. Los archivos de datos basados en tar o en zip (archivos creados con la clasePharDataclass) deben tener su signatura creada y establecerla explícitamente mediantePhar::setSignatureAlgorithm().
sigtypeUna de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL
privatekeyEl contenido de una clave privada OpenSSL, como la extraída de un certificado o de un fichero de clave OpenSSL:
<?php
$private=openssl_get_privatekey(file_get_contents('private.pem'));
$pkey='';
openssl_pkey_export($private,$pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL,$pkey);
?>No devuelve ningún valor.
Lanza una excepción de tipoUnexpectedValueExceptionpara muchos errores, y una excepción de tipoPharExceptionsi ocurrió algún problema al volcar los cambios al disco.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::setStub—Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
$stub,int$len= -1):boolNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Este método se utiliza para añadir una rutina de interoperabilidad cargadora a un nuevo archivo Phar, o reemlazar la rutina de interoperabilidad de un archivo Phar existente.
La rutina de interoperabilidad cargadora de un archivo Phar se utiliza siempre que un archivo esté incluido directamente como en este ejemplo:
<?php
include'miphar.phar';
?>Al cargador no se accede cuando se incluye un archivo a través de la envoltura de flujospharcomo aquí:
<?php
include'phar://miphar.phar/un_fichero.php';
?>stubUna cadena o un gestor de flujo abierto para usarlo como la rutina de interoperabilidad ejecutable de este archivo phar.
lenDevuelvetrueen caso de éxito ofalseen caso de error.
Se lanza una excepción de tipoUnexpectedValueExceptionsiphar.readonlyestá habilitado en php.ini. Se lanza una excepción de tipoPharExceptionsi se encuentra cualquier problema al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::setStub()
<?php
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['a.php'] ='<?php var_dump("Hola");';
$p->setStub('<?php var_dump("Primero"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>');
include'phar://nuevo_phar.phar/a.php';
var_dump($p->getStub());
$p['b.php'] ='<?php var_dump("Mundo");';
$p->setStub('<?php var_dump("Segundo"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>');
include'phar://nuevo_phar.phar/b.php';
var_dump($p->getStub());
} catch (Exception $e) {
echo'Las operaciones de escritura sobre nuevo_phar.phar fallaron: ',$e;
}
?>El resultado del ejemplo sería:
string(4) "Hola"
string(84) "<?php var_dump("Primero"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>"
string(5) "Mundo"
string(84) "<?php var_dump("Segundo"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>"
| Versión | Descripción |
|---|---|
| 5.4.0 | Se añadió el parámetrolen. |
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::startBuffering—Iniciar las operaciones de escritura en buffer de Phar, no modifica el objeto Phar del disco
Aunque es técnicamente innecesario, el métodoPhar::startBuffering()puede proporcionar un aumento significativo de rendimiento al crear o modificar un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro de un archivo Phar es creado o modificado de alguna manera, el archivo Phar entero se re-creará con los cambios. De esta forma, el archivo estará actualizado con la actividad realizada sobre él.
Sin embargo, esto puede ser innecesario al crear simplemente un nuevo archivo Phar, que tendría más sentido escribir el archivo entero de una vez. De forma similar, a menudo es necesario realizar una serie de cambios y asegurarse de que todos son posibles antes de hacer cualquier cambio en disco, similar al concepto de transacciones en bases de datos relacionales. La pareja de métodosPhar::startBuffering()/Phar::stopBuffering()está prevista para este propósito.
La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.
No devuelve ningún valor.
Ejemplo #1 Un ejemplo dePhar::startBuffering()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
} catch (Exception $e) {
echo'No se pudo crear el phar:',$e;
}
echo'El nuevo phar tiene '.$p->count() ." entradas\n";
$p->startBuffering();
$p['fichero.txt'] ='hola';
$p['fichero2.txt'] ='qué tal';
$p['fichero2.txt']->setCompressedGZ();
$p['fichero3.txt'] ='cara de niño';
$p['fichero3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload($clase)
{
include 'phar://miphar.phar/' . str_replace('_', '/',$clase) . '.php';
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/inicio.php';
__HALT_COMPILER();");
$p->stopBuffering();
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::stopBuffering—Detener las peticiones de escritura en buffer del archivo Phar, y guardar los cambios en disco
Phar::stopBuffering()se usa junto con el métodoPhar::startBuffering().Phar::startBuffering()puede proporcionar un aumento significativo de rendimiento al crear o modificar un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro de un archivo Phar es creado o modificado de alguna manera, el archivo Phar entero se re-creará con los cambios. De esta forma, el archivo estará actualizado con la actividad realizada sobre él.
Sin embargo, esto puede ser innecesario al crear simplemente un nuevo archivo Phar, que tendría más sentido escribir el archivo entero de una vez. De forma similar, a menudo es necesario realizar una serie de cambios y asegurarse de que todos son posibles antes de hacer cualquier cambio en disco, similar al concepto de transacciones en bases de datos relacionales. La pareja de métodosPhar::startBuffering()/Phar::stopBuffering()está prevista para este propósito.
La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.
No devuelve ningún valor.
Se lanza una excepción de tipoPharExceptionsi se encontró algún problema volcando los cambios al disco.
Ejemplo #1 Un ejemplo dePhar::stopBuffering()
<?php
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero1.txt'] ='hola';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$clase)
{
include 'phar://nuevo_phar.phar/' . str_replace('_', '/', \$clase) . '.php';
}
Phar::mapPhar('nuevo_phar.phar');
include 'phar://nuevo_phar.phar/incio.php';
__HALT_COMPILER();");
$p->stopBuffering();
var_dump($p->getStub());
?>El resultado del ejemplo sería:
string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($clase)
{
include 'phar://' . str_replace('_', '/', $clase);
}
Phar::mapPhar('nuevo_phar.phar');
include 'phar://nuevo_phar.phar/incio.php';
__HALT_COMPILER();"
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::unlinkArchive—Elimiar completamente un archivo phar del disco y de la memoria
$archive):boolElimina un archivo phar del disco y de la memoria.
archiveLa ruta en el disco al archivo phar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Se lanza una excepción de tipoPharExceptionsi existe cualquier fichero abierto que apunte al archivo phar, o cualquier objeto existente de las clasesPhar,PharData, oPharFileInfoque haga referencia al archivo phar.
Ejemplo #1 Un ejemplo dePhar::unlinkArchive()
<?php
// uso simple
Phar::unlinkArchive('/ruta/a/mi.phar');
// ejemplo más común:
$p= newPhar('mi.phar');
$fp=fopen('phar://mi.phar/fichero.txt','r');
// esto crea 'mi.phar.gz'
$gp=$p->compress(Phar::GZ);
// eliminar todas las referencias al archivo
unset($p);
fclose($fp);
// ahora, eliminar todas los indicions del archivo
Phar::unlinkArchive('mi.phar');
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
Phar::webPhar—mapPhar para archivos phar basados en web. Controlador principal para aplicaciones web
$alias= ?,$index= "index.php",$f404= ?,$mimetypes= ?,$rewrites= ?Phar::mapPhar()para archivos phar basados en web. Este método procesa$_SERVER['REQUEST_URI']y direcciona una petición de un navegador web a un fichero interno dentro de un archivo phar. En esencia, simula un servidor web, direccionando las peticiones al fichero correcto, enviando las cabeceras correctas y procesando ficheros PHP según sea necesario. Este poderoso método es parte de lo que hace sencillo convertir una apliación PHP existene en un archivo phar. Combinado conPhar::mungServer()yPhar::interceptFileFuncs(), cualquier aplicación web se puede utilizar sin modificaciones desde un archivo phar.
Phar::webPhar()debería llamarse solamente desde la rutina de interoperabilidad (stub) de un archivo phar (aquíhay más información de lo que es una rutina de interorperabilidad).
aliasEl alias que puede usarse en las URLphar://para referirse a este archivo, en vez de su ruta completa.
indexLa ubicación dentro del phar del índice de directorios.
f404La ubicación del script a ejecutar cuando no se encuentra el fichero. Este script debería mostrar las cabeceras HTTP 404 apropiadas.
mimetypesUn array que mapea extensiones de fichero adicionales a tipos de MIME. Si el mapeo predeterminado es suficiente, se ha de pasar un array vacío. Por omisión, estas extensiones son mapeadas a estos tipos de MIME:
<?php
$mimes= array(
'phps'=>Phar::PHPS,// pasa a highlight_file()
'c'=>'text/plain',
'cc'=>'text/plain',
'cpp'=>'text/plain',
'c++'=>'text/plain',
'dtd'=>'text/plain',
'h'=>'text/plain',
'log'=>'text/plain',
'rng'=>'text/plain',
'txt'=>'text/plain',
'xsd'=>'text/plain',
'php'=>Phar::PHP,// procesado como PHP
'inc'=>Phar::PHP,// procesado como PHP
'avi'=>'video/avi',
'bmp'=>'image/bmp',
'css'=>'text/css',
'gif'=>'image/gif',
'htm'=>'text/html',
'html'=>'text/html',
'htmls'=>'text/html',
'ico'=>'image/x-ico',
'jpe'=>'image/jpeg',
'jpg'=>'image/jpeg',
'jpeg'=>'image/jpeg',
'js'=>'application/x-javascript',
'midi'=>'audio/midi',
'mid'=>'audio/midi',
'mod'=>'audio/mod',
'mov'=>'movie/quicktime',
'mp3'=>'audio/mp3',
'mpg'=>'video/mpeg',
'mpeg'=>'video/mpeg',
'pdf'=>'application/pdf',
'png'=>'image/png',
'swf'=>'application/shockwave-flash',
'tif'=>'image/tiff',
'tiff'=>'image/tiff',
'wav'=>'audio/wav',
'xbm'=>'image/xbm',
'xml'=>'text/xml',
);
?>rewritesA la función rewrites se le proporciona un string como único parámetro y debe devolver unstringofalse.
Si se está utilizando fast-cgi o cgi, el parámetro pasado a la función es el valor de la variable$_SERVER['PATH_INFO']. De otro modo, el parámetro pasado a la función es el valor de la variable$_SERVER['REQUEST_URI'].
Si se devuelve un string, este se usa como la ruta de fichero interno. Si se devuelvefalse, webPhar() enviará un código de rechazo HTTP 403.
No devuelve ningún valor.
Lanza una excepción de tipoPharExceptioncuando no se puede abrir el fichero interno para salida, o si se llama desde un lugar que no sea una rutina de interoperabilidad. Si se pasa un array no válido amimetypeso se proporciona una llamada de retorno no válida arewrites, se lanza una excepción de tipoUnexpectedValueException.
Ejemplo #1 Un ejemplo dePhar::webPhar()
Con el ejemplo siguiente, el phar creado mostraráHola Mundosi uno explora/miphar.phar/index.phpo/miphar.phar, y mostrará la fuente deindex.phpssi uno explora/miphar.phar/index.phps.
<?php
// creating the phar archive:
try {
$phar= newPhar('miphar.phar');
$phar['index.php'] ='<?php echo "Hola Mundo"; ?>';
$phar['index.phps'] ='<?php echo "Hola Mundo"; ?>';
$phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
La clase PharData proporciona una interfaz de alto nivel para el acceso y la creación de archivos tar y zip no ejecutables. Debido a que estos archivos no contienen una rutina de interoperabilidad y no pueden ser ejecutados por la extensión phar, es posible crear y manipular ficheros zip y tar normales con la clase PharData incluso si la opción del php.iniphar.readonlyestá establecida a1.
$format= 9021976,int$compression= 9021976,string$extension= ?):PharData$format= 9021976,int$compression= 9021976,string$extension= ?):Phar$alias= ?,$index= "index.php",$f404= ?,$mimetypes= ?,$rewrites= ?(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::addEmptyDir—Añadir un directorio vacío al archivo tar/zip
$dirname):boolCon este método se crea un directorio vacío con la ruta dada pordirname. Este método es similar aZipArchive::addEmptyDir().
dirnameEl nombre de directorio vacío a crear en el archivo tar o zip
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePharData::addEmptyDir()
<?php
try {
$a= newPharData('/ruta/a/phar.phar');
$a->addEmptyDir('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->isDir();
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::addFile—Añadir un fichero desde el sistema de ficheros al archivo tar/zip
Con este método, cualquier fichero o URL se puede añadir al arcivo tar/zip. Si se especifica el segundo parámetro opcionallocalname, el fichero será almacenado en el archivo con el nombre dado por el parámetro, si no se usará el parámetrofilecomo la ruta para almacentar dentro del archivo. Las URLs deben tener un nombre local o se lanzará una excepción. Este método es similar aZipArchive::addFile().
fileLa ruta completa o relativa del fichero del disco a ser añadido al archivo phar.
localnameRuta con la que el fichero será almacenado en el archivo.
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePharData::addFile()
<?php
try {
$a= newPharData('/ruta/a/phar.phar');
$a->addFile('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->getContent();
$a->addFile('/ruta/completa/a/fichero','mi/fichero.txt');
$c=$a['mi/fichero.txt']->getContent();
// demostrar el uso de una URL
$a->addFile('http://www.ejemplo.com','ejemplo.html');
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::addFromString—Añadir un fichero desde el sistema de ficheros al archivo tar/zip
$localname,string$contents):boolCon este método, cuanquierl cadena se puede añadir al archivo tar/zip. El fichero será almacenado en el archivo conlocalnamecomo su ruta. Este método es similar aZipArchive::addFromString().
localnameRuta con la que el fichero será almacenado en el archivo.
contentsEl contenido del fichero a almacenar
No devuelve ningún valor, se lanza una excepción en caso de error.
Ejemplo #1 Un ejemplo dePharData::addFromString()
<?php
try {
$a= newPharData('/ruta/a/phar.phar');
$a->addFromString('ruta/a/fichero.txt','mi sencillo fichero');
$b=$a['ruta/a/fichero.txt']->getContent();
// para añadir contenido desde un gestor de flujos para ficheros grandes, use offsetSet()
$c=fopen('/ruta/a/fichero_enorme.bin');
$a['fichero_grande.bin'] =$c;
fclose($c);
} catch (Exception $e) {
// manejar los errores aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::buildFromDirectory—Construir un archivo tar/zip desde los ficheros de un directorio
Rellena un archivo phar con el contenido de un directorio. El segundo parámtro opcional es una expresión regular (pcre) que se utiliza para excluir ficheros. Cualquier nombre de fichero que coincida con la expresión regular será incluido, todos los demás serán excluidos. Para un control más exhaustivo, usePharData::buildFromIterator().
base_dirLa ruta completa o relativa al directorio que contiene todos los ficheros a añadir al archivo.
regexUna expresión regular de pcre opcional que se usa para filtrar la lista de ficheros. Solamente las rutas de fichero que coincidan con la expresión regular serán incluidas en el archivo.
Phar::buildFromDirectory()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no puede instanciar los iteradores intermos del directorio, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.
Ejemplo #1 Un ejemplo dePharData::buildFromDirectory()
<?php
$phar= newPharData('proyecto.tar');
// añadir todos los ficheros del proyecto
$phar->buildFromDirectory(dirname(__FILE__) .'/proyecto');
$phar2= newPharData('proyecto2.zip');
// añadir todos los ficheros del, incluir solamente los ficheros php
$phar2->buildFromDirectory(dirname(__FILE__) .'/proyecto','/\.php$/');
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::buildFromIterator—Construir un archivo tar o zip desde un iterador
Rellena un archivo tar o zip desde un iterador. Están soportados dos estilos de iteradores, los iteradores que mapean el nombre de fichero dentro del tar/zip al nombre del fichero en disco, y los iteradores como DirectoryIterator que devuelven objetos de la clase SplFileInfo. Se requiere el segundo parámetro para los iteradores que devuelven objetos de la clase SplFileInfo.
Ejemplo #1 Un ejemplo dePharData::buildFromIterator()con SplFileInfo
Para la mayoría de los archivos tar/zip, el archivo reflejará la distribución real de directorios, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo tar/zip que contenga los ficheros n esta distribución de muestra de directorios:
/ruta/al/proyecto/
config/
dist.xml
debug.xml
lib/
fichero1.php
fichero2.php
src/
procesa_algo.php
www/
index.php
cli/
index.phpEste código podría usarse para añadir estos ficheros al archivo tar "proyecto.tar":
<?php
$phar= newPharData('proyecto.tar');
$phar->buildFromIterator(
newRecursiveIteratorIterator(
newRecursiveDirectoryIterator('/ruta/al/proyecto')),
'/ruta/al/proyecto');
?>El ficheroproject.tarse puede usar inmediatamente.PharData::buildFromIterator()no establece valores como la compresión y metainformación, que se puede hacer después de crear el archivo tar/zip.
Como observación interesante,PharData::buildFromIterator()también se puede usar para copiar el contenido de un archivo phar, tar o zip existentese, ya que los objetos de la clase PharData descienden de la claseDirectoryIterator:
<?php
$phar= newPharData('proyecto.tar');
$phar->buildFromIterator(
newRecursiveIteratorIterator(
newPhar('/ruta/a/otro_phar.phar')),
'phar:///ruta/a/otro_phar.phar/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>Ejemplo #2 Un ejemplo dePharData::buildFromIterator()con otros iteradores
La segunda forma de iterador se puede usar con cualquier iterador que devuelva un mapeo clave => valor, tal como un objeto de la claseArrayIterator:
<?php
$phar= newPharData('proyecto.tar');
$phar->buildFromIterator(
newArrayIterator(
array(
'fichero/interno.php'=>dirname(__FILE__) .'/algun_fichero.php',
'otro/fichero.jpg'=>fopen('/rota/a/archivo_grande.jpg','rb'),
)));
?>iterCualquier iterador que mapee de forma asociativa el fichero tar/zip a la ubiciación o que devuelva objetos de la clase SplFileInfo
base_directoryPara los iteradores que devuelven objetos de la clase SplFileInfo, es la porción de cada ruta completa de fichero a eliminar cuando de añada al archivo tar/zip
PharData::buildFromIterator()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.
Este método lanza una excepción de tipoUnexpectedValueExceptioncuando el iterador devuelve valores incorrectos, tales como una clave de tipo integer en lugar de una cadena, una excepción de tipoBadMethodCallExceptioncuando se pasa un iterador basado en SplFileInfo sin un parámetrobase_directory, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::compress—Comprimir el archivo tar/zip entero usando la compresión Gzip o Bzip2
$compression,string$extension= ?):objectPara archivos tar, este método comprime el archivo entero usando la compresión gzip o bzip2. El fichero resultante puede ser procesado con el comando gunzip/bunzip, o se puede acceder a él directa y transparentemente con la extensión Phar.
Para archivos phar basados en Zip, este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para poder comprimir con la compresión gzip, y la extensiónbzip2debe estar habilitada para poder comprimir con la compresión bzip2.
Además, este método renombra automáticamente el archivo, añadiéndole.gz,.bz2o eliminado la extensión si se pasaPhar::NONEpara eliminar la compresión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.
compressionLa compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.
extensionPor omisión, la extensión es.tar.gzo.tar.bz2para comprimir un tar, y.tarpara descomprimirlo.
Devuelve un objeto de la clasePharData.
Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePharData::compress()
<?php
$p= newPharData('/ruta/a/mi.tar');
$p['myfile.txt'] ='hi';
$p['myfile2.txt'] ='hi';
$p1=$p->compress(Phar::GZ);// copia a /ruta/a/mi.tar.gz
$p2=$p->compress(Phar::BZ2);// copia a /ruta/a/mi.tar.bz2
$p3=$p2->compress(Phar::NONE);// excepción: /ruta/a/mi.tar ya existe
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::compressFiles—Comprime todos los ficheros del archivo tar/zip actual
$compression):boolPara archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.
Para achivos basados en Zip, este método comprime todos los ficheros del archivo usando la compresión especificada. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica. Además, si cualquier fichero ya está comprimido con la compresión bzip2/zlib, la extensión respectiva debe estar habilitada para poder descomprimir los ficheros antes de re-comprimirlos.
compressionLa compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePharData::compressFiles()
<?php
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>El resultado del ejemplo sería:
string(13) "mifichero.txt" bool(false) bool(false) bool(false) string(14) "mifichero2.txt" bool(false) bool(false) bool(false) string(13) "mifichero.txt" int(4096) bool(false) bool(true) string(14) "mifichero2.txt" int(4096) bool(false) bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::__construct—Construir un objeto de archivo tar o zip no ejecutable
$fname,$flags= ?,$alias= ?,$format=Phar::TARfnameRuta a un archivo tar/zip existente o para ser creado
flagsBanderas a pasar a la clase padreRecursiveDirectoryIterator.
aliasAlias con el que referirse al archivo Phar en las llamadas a funcionalidades de flujos.
formatUna de lasconstantes de formato de ficherodisponiblies dentro de la clasePhar.
Lanza una excepción de tipoBadMethodCallExceptionsi se llama dos veces, o una excepción de tipoUnexpectedValueExceptionsi no se puede abrir el archivo phar.
Ejemplo #1 Un ejemplo dePharData::__construct()
<?php
try {
$p= newPharData('/ruta/a/mi.tar',Phar::CURRENT_AS_FILEINFO|Phar::KEY_AS_FILENAME);
} catch (UnexpectedValueException $e) {
die('No se pudo abrir mi.tar');
} catch (BadMethodCallException $e) {
echo'Técnicamente esto no puede suceder';
}
echofile_get_contents('phar:///ruta/a/mi.tar/ejemplo.txt');
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::convertToData—Convertir un archivo phar en un fichero tar o zip no ejecutable
Este método se usa para convertir un archivo tar o zip no ejecutable a otro formato no ejecutable.
Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallExceptionEste método debería usarse para convertir un archivo tar a formato zip o viceversa. Aunque es posible cambiar la compresión de un archivo tar simplemente usando este método, es mejor utilizad el métodoPharData::compress()para una consistencia lógica.
En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.
formatEste parámetro debería serPhar::TARoPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.
compressionEste parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.
extensionEste parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que.pharno puede ser usado en ningún lugar del nombre de fichero de un archivo tar o zip no ejecutable.
Si se convierte a un archivo basado en tar, las extensiones predeterminadas son.tar,.tar.gz, y.tar.bz2dependiendo de la compresión especificada. Para archivos basados en zip, la extensión predetermianda es.zip.
El método devuelve un objetoPharDataen caso de éxito, y lanza una excepción en caso de error.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.
Ejemplo #1 Un ejemplo dePharData::convertToData()
Utilizar PharData::convertToData():
<?php
try {
$tarphar= newPharData('miphar.tar');
// observe que miphar.phar.tar *no* está desvinculado.
// convertirlo a un formato de fichero tar no ejecutable,
// se crea miphar.zip
$zip=$tarphar->convertToData(Phar::ZIP);
// crear miphar.tbz
$tgz=$tarphar->convertToData(Phar::TAR,Phar::BZ2,'.tbz');
// crear miphar.phar.tgz
$phar=$tarphar->convertToData(Phar::PHAR);// lanza una excepción
} catch (Exception $e) {
// manejar el error aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::convertToExecutable—Convertir un archivo tar/zip no ejecutable en un archivo phar ejecutable
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Este método se utiliza para convertir un arhivo tar o zip no ejecutable en un archivo phar ejecutable. Se puede usar cualquiera de los tres formatos de fichero (phar, tar o zip), y también se puede realizar la compresión del archivo completo.
Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallException
En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado. If successful, the method creates a new archive on disk and returns aPharobject. The old archive is not removed from disk, and should be done manually after the process has finished.
formatEste parámetro debería serPhar::PHAR,Phar::TAR, oPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.
compressionEste parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.
extensionEste parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que todos los archivos phar basados en zip o en tar deben contener.pharen su extensión de fichero para poder ser procesados como un archivo phar.
Si se convierte a un archivo basado en phar, las extensiones predeterminadas son.phar,.phar.gz, o.phar.bz2dependiendo de la compresión especificada. Para archivos phar basados en tar, las extensiones predeterminadas son.phar.tar,.phar.tar.gz, y.phar.tar.bz2. Para archivos phar basados en zip, la estensión predeterminada es.phar.zip.
El método devuelve un objetoPharen caso de éxito, y lanza una excepción en caso de error.
Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), una excepción de tipoUnexpectedValueExceptionsi el soporte para escritura está deshabilitado, y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.
Ejemplo #1 Un ejemplo dePharData::convertToExecutable()
Utilizar PharData::convertToExecutable():
<?php
try {
$tarphar= newPharData('miphar.tar');
// convertirlo al formato de fichero phar
// observe que miphar.tar *no* está desvinculado
$phar=$tarphar->convertToExecutable(Phar::PHAR);// crea miphar.phar
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
// crea miphar.phar.tgz
$comprimido=$tarphar->convertToExecutable(Phar::TAR,Phar::GZ,'.phar.tgz');
} catch (Exception $e) {
// manejar el error aquí
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::copy—Copiar un fichero interno de un archivo phar a otro fichero nuevo dentro del phar
$oldfile,string$newfile):boolCopia un fichero interno de un archivo tar/zip a otro fichero nuevo dentro del mismo archivo. Esta es una alternativa orientada a objetos para usarcopy()con la envoltura de flujos phar.
oldfilenewfileDevuelvetrueen caso de éxito, pero es más seguro encerrar la llamada al método en un bloque try/catch y asumir el éxito si no se lanza ninguna excepción.
Lanza una excepción de tipoUnexpectedValueExceptionsi el fichero origen no exite, el fichero destino ya existe, el acceso a escritura está deshabilitado, la apertura de cualquiera de los dos ficheros falla, la lectura del fichero fuente falla, o una excepción de tipoPharExceptionsi la escritura de los cambios del phar falla.
Ejemplo #1 Un ejemplo dePhar::copy()
Este ejemplo muestra el uso dePharData::copy()y su equivalente con envoltura de flujos. La principal diferencia entre los dos enfoques es el manejo de errores. Todos los métodos de PharData lanzan excepciones, mientras que la envoltura de flujos utilizatrigger_error().
<?php
try {
$phar= newPharData('miphar.tar');
$phar['a'] ='hola';
$phar->copy('a','b');
echo$phar['b'];// imprime "phar://miphar.tar/b"
} catch (Exception $e) {
// manejar errores
}
// el equivalente con envoltura de flujos del código de arriba.
// Se dispara E_WARNINGS en caso de error en vez de excepciones.
copy('phar://miphar.tar/a','phar//miphar.tar/c');
echofile_get_contents('phar://miphar.tar/c');// imprime "hola"
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::decompress—Descomprimir un archivo Phar entero
$extension= ?):objectPara archivos phar basados en tar, este método descomprime el archivo entero.
Para archivos phar basados en Zip, este método este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para descomprimir un archivo comprimido con la compresión gzip, y la extensiónbzip2debe estar habilitada para descomprimir un archivo comprimido con la compresión bzip2.
Además, este método renombra automáticamente la extensión de fichero del archivo,.tarpor omisión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.
extensionPara la descompresión, las extensión de fichero predeterminada es.phar.tar. Use este parámetro para especificar otra extensión de fichero. Observe que todos los archivos no ejecutables no pueden contener.pharen su nombre de fichero.
Devuelve un objeto de la clasePharData.
Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.
Ejemplo #1 Un ejemplo dePharData::decompress()
<?php
$p= newPharData('/ruta/a/mi.tar.gz');
$p->decompress();// crea /ruta/a/mi.tar
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::decompressFiles—Descomprimir todos los ficheros del archivo zip actual
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Para archivos basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.
Para achivos phar basados en Zip y phar, este método descomprime todos los ficheros del archivo. Las extensioneszlibobzip2deben estar habilitadas para aprvechar esta característica si cualquier fichero está comprimido con la compresión bzip2/zlib.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada. ThrowsBadMethodCallExceptionif thezlibextension is not available, or if any files are compressed using bzip2 compression and thebzip2extension is not enabled.
Ejemplo #1 Un ejemplo dePharData::decompressFiles()
<?php
$p= newPharData('/ruta/a/mi.zip');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p->compressFiles(Phar::GZ);
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>El resultado del ejemplo sería:
string(13) "mifichero.txt" int(4096) bool(false) bool(true) string(14) "mifichero2.txt" int(4096) bool(false) bool(true) string(13) "mifichero.txt" bool(false) bool(false) bool(false) string(14) "mifichero2.txt" bool(false) bool(false) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::delMetadata—Eliminar la metainformación global de un archivo zip
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Elimina la metainformación global de un archivo zip
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePharData::delMetaData()
<?php
try {
$phar= newPharData('miphar.zip');
var_dump($phar->getMetadata());
$phar->setMetadata("hola, qué tal");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// manejar errores
}
?>El resultado del ejemplo sería:
NULL string(14) "hola, qué tal" NULL
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::delete—Borrar un fichero dentro de un archivo tar/zip
$entry):boolBorra un fichero dentro de un archivo. Esto es el equivalente funcional de llamar aunlink()en el equivalente de envoltura de flujos, tal como se muestra en el ejemplo de abajo.
entryLa ruta dentro de un archivo para borrar el fichero.
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi se produjo algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePharData::delete()
<?php
try {
$phar= newPharData('miphar.zip');
$phar->delete('desvincular/yo.php');
// esto es equivalente a:
unlink('phar://miphar.phar/desvincular/yo.php');
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::__destruct—Destructs a non-executable tar or zip archive object
Esta función no tiene parámetros.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::extractTo—Extraer el contenido de un archivo tar/zip a un directorio
$pathto,string|array$files= ?,bool$overwrite= false):boolExtrae todos los ficheros de un archivo tar/zip al disco. Los ficheros y directorios extraídos conservan los mismos permisos que los almacenados en el archivo. Los parámetros opcionales permiten controlar qué ficheros serán extraídos, y si los ficheros existentes en disco podrán ser sobrescritos. El segundo parámetrofilespuede ser el nombre de un fichero o directorio a extraer, o un array de nombre de ficheros y directorios a extraer. Por omisión, este método no sobrescribirá los ficheros existentes, aunque el tercer parámetro se puede establecer a true para habilitar la sobrescritura de ficheros. Este método es similar aZipArchive::extractTo().
pathtoRuta donde extraer los ficheros dados porfiles
filesEl nombre de un fichero o directorio a extraer, o un array de ficheros/directorios a extraer.
overwriteEsteblecer atruepara habilitar la sobrescritura de ficheros existentes
Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.
Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.
Ejemplo #1 Un ejemplo dePharData::extractTo()
<?php
try {
$phar= newPharData('miphar.tar');
$phar->extractTo('/ruta/completa');// extraer todos los ficheros
$phar->extractTo('/otra/ruta','fichero.txt');// extraer solamente fichero.txt
$phar->extractTo('/esta/ruta',
array('fichero1.txt','fichero2.txt'));// extraer solamente 2 ficheros
$phar->extractTo('/tercera/ruta',null,true);// extraer todos los ficheros y sobrescribirlos
} catch (Exception $e) {
// manejar errores
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::isWritable—Devolver si el archivo tar/zip se puede modificar
Este método devuelvetruesi el archivo tar/zip archive del disco no es de sólo lectura. A diferencia dePhar::isWritable(), los archivos tar/zip de sólo datos se pueden modificar incluso siphar.readonlyestá establecido a1.
No tiene parámetros.
Devuelvetruesi el archivo tar/zip puede ser modificado
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::offsetSet—Establecer el contenido de un fichero dentro de un tar/zip a aquel de un fichero o cadena externos
$offset,string$value):voidÉsta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes de acceso al array. offsetSet se utiliza para modificar un fichero existente, o añadir un nuevo fichero al archivo tar/zip.
offsetEl nombre del fichero (ruta relativa) a modificar en un archivo tar o zip.
valueEl contenido del fichero.
No devuelve ningún valor.
Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo tar/zip al disco.
Ejemplo #1 Un ejemplo dePharData::offsetSet()
No se debería acceder directamente a offsetSet, en su lugar se utiliza el operador[]para acceder al array.
<?php
$p= newPharData('/ruta/a/mi.phar',0,'mi.phar');
try {
// llama a offsetSet
$p['fichero.txt'] ='Hola qué tal';
} catch (Exception $e) {
echo'No se pudo modificar fichero.txt:',$e;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::offsetUnset—Eliminar un ficerho de un archivo tar/zip
$offset):boolÉsta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes de acceso al array. offsetUnset se utiliza para borrar un fichero existente, y es llamado por el constructor de lenguajeunset().
offsetEl nombre del fichero (ruta relativa) a eliminar en un archivo tar o zip.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo tar/zip al disco.
Ejemplo #1 Un ejemplo dePharData::offsetUnset()
<?php
$p= newPharData('/ruta/a/mi.phar',0,'mi.phar');
try {
// borra fichero.txt de mi.phar llamando a offsetUnset
unset($p['fichero.txt']);
} catch (Exception $e) {
echo'No se pudo borrar fichero.txt: ',$e;
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::setAlias—función sin sentido (Phar::setAlias no es válido para PharData)
$alias):boolLos archivos tar/zip no ejecutables no pueden tener un alias, por lo que este método simplemente lanza una excepción.
aliasUna cadena abreviada para referirse a este archivo en el acceso con la envoltura de flujophar. Este parámetro es ignorado.
Lanza una excepción de tipoPharExceptionen todas las llamdas al método
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::setDefaultStub—función sin sentido (Phar::setStub no es válido para PharData)
$index= ?,string$webindex= ?):boolLos archivos tar/zip no ejecutables no pueden tener una rutina de interoperabilidad, por lo que este método simplemente lanza una excepción.
indexLa ruta relativa dentro del archivo phar a ejectuar si se accede desde la línea de comandos
webindexLa ruta relativa dentro del archivo phar a ejectuar si se accede desde un servidor web
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoPharExceptionen todas las llamadas al método
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
Phar::setMetadata—Establecer la metainformación de un archivo phar
Nota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Phar::setMetadata()debería usarse para almacenar información personalizada que describa algo sobre el archivo phar como una entidad completa.PharFileInfo::setMetadata()debería usarse para metainformación específica de cada fichero. La metainformación puede ralentizar la velocidad de carga de un archivo phar si la información es grande.
Algunos posibles usos para la metainformación incluyen especificar qué fichero dentro del archivo debería usarse para cargar el archivo, o la ubicación de un fichero de manifiesto como el fichero package.xml de» PEAR. Sin embargo, se puede almacenar cualquier información útil que describa el archivo phar.
metadataCualquier variable de PHP que contenga la información a almacenar que describa el archivo phar
No devuelve ningún valor.
Ejemplo #1 Un ejemplo dePhar::setMetadata()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola"';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo'No se pudo crear y/o modificar el phar:',$e;
}
?>El resultado del ejemplo sería:
array(1) {
["bootstrap"]=>
string(11) "fichero.php"
}
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm—Establecer el algoritmo de firma para un phar y aplicarlo
$sigtype):voidNota:
Este método requiere que la opción dephp.ini
phar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.
Establece el algoritmo de firma para un phar y lo aplica. El algoritmo de firma debe ser una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL. (PGP aún no está soportado y se recurre a SHA-1).
sigtypeUna de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, orPhar::PGP
No devuelve ningún valor.
Lanza una excepción de tipoUnexpectedValueExceptionpara muchos errores, una excepción de tipoBadMethodCallExceptionsi se llamó para un archivo basao en zip o en tar, y una excepción de tipoPharExceptionsi ocurrió algún problema al volcar los cambios al disco.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharData::setStub—función sin sentido (Phar::setStub no es válido para PharData)
$stub,int$len= -1):boolLos archivos tar/zip no ejecutables no pueden tener una rutina de interoperabilidad, por lo que este método simplemente lanza una excepción.
stubUna cadena o un gestor de flujo abierto para usarlo como la rutina de interoperabilidad ejecutable de este archivo phar. Este parámetro es ignorado.
lenDevuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoPharExceptionen todas las llamadas al método
| Versión | Descripción |
|---|---|
| 5.4.0 | Se añadió el parámetrolen. |
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
La clase PharFileInfo proporciona una interfaz de alto nivel para el contenido y los atributos de un único fichero dentro de un archivo phar.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::chmod—Esteblecer los bits de permiso específicos del fichero
$permissions):voidPharFileInfo::chmod()permite el ajuste del bit de permiso ejecutable de un fichero, así como el bit de sólo lectura. El bit de escritura se ignora, y se establece en tiempo de ejecución basándose en la variable INIphar.readonly. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.
permissionsLos permisos (véasechmod())
No devuelve ningún valor.
Ejemplo #1 Un ejemplo dePharFileInfo::chmod()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar('nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.sh'] ='#!/usr/local/lib/php
<?php echo "hi"; ?>';
// establecer el bit ejecutable
$p['fichero.sh']->chmod(0555);
var_dump($p['fichero.sh']->isExecutable());
} catch (Exception $e) {
echo'No se pudo crear/modificar el phar: ',$e;
}
?>El resultado del ejemplo sería:
bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharFileInfo::compress—Comprimir la entrada del Phar actual con la compresión zlib o bzip2
$compression):boolEste método comprime el fichero dentro de un archivo Phar usando la compresión bzip2 o zlib. Las extensionesbzip2ozlibdeben estar habilitadas para aprovechar esta característica. Además, si el fichero ya está comprimido, la extensión respectiva debe estar habilitada para poder descomprimir el fichero. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónbzip2/zlibno está disponible.
Ejemplo #1 Un ejemplo dePharFileInfo::compress()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->isCompressed(Phar::BZ2));
$p['mifichero.txt']->compress(Phar::BZ2);
var_dump($fichero->isCompressed(Phar::BZ2));
} catch (Exception $e) {
echo'Falló la operación de crear/modificar mi.phar: ',$e;
}
?>El resultado del ejemplo sería:
bool(false) bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::__construct—Construir un objeto de entrada Phar
$entry)Este método no debería llamarse directamente. En su lugar, un objeto de la clase PharFileInfo se inicializa al llamar aPhar::offsetGet()a traves del acceso a un array.
entryLa URL completa para recuperar un fichero. Si se desea recuperar la informacion del fichoermi/fichero.phpdesde el pharboo.phar, la entrada debería serphar://boo.phar/mi/fichero.php.
Lanza una excepción de tipoBadMethodCallExceptionsi__construct()es llamado dos veces. Lanza una excepción de tipoUnexpectedValueExceptionsi la URL del phar solicitado está malformada, el phar solicitado no se puede abrir, o el fichero no se puede encontrar dentro del phar.
Ejemplo #1 Un ejemplo dePharFileInfo::__construct()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['fichero_prueba.txt'] ="hola\nqué tal\namigo";
$fichero=$p['fichero_prueba.txt'];
foreach ($ficheroas$línea=>$texto) {
echo"línea número$línea:$texto";
}
// esto también funciona
$fichero= newPharFileInfo('phar:///ruta/a/mi.phar/fichero_prueba.txt');
foreach ($ficheroas$línea=>$texto) {
echo"línea número$línea:$texto";
}
} catch (Exception $e) {
echo'Las operaciones Phar fallaron: ',$e;
}
?>El resultado del ejemplo sería:
línea número 1: hola línea número 2: qué tal línea número 3: amigo línea número 1: hola línea número 2: qué tal línea número 3: amigo
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)
PharFileInfo::decompress—Descomprimir la entrada Phar actual dentro del phar
Este método descompribe el fichero dentro de un archivo Phar. Dependiendo de cómo esté comprimido el fichero, las extensionesbzip2ozlibdeben estar habilitadas para aprovechar esta característica. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.
Devuelvetrueen caso de éxito ofalseen caso de error.
Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónbzip2/zlibno está disponible.
Ejemplo #1 Un ejemplo dePharFileInfo::decompress()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
$fichero->compress(Phar::GZ);
var_dump($fichero->isCompressed());
$p['mifichero.txt']->decompress();
var_dump($fichero->isCompressed());
} catch (Exception $e) {
echo'La operación de crear/modificar mi.phar falló: ',$e;
}
?>El resultado del ejemplo sería:
int(4096) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
PharFileInfo::delMetadata—Eliminar la metainformación de una entrada
Eliminar la metainformación de una entrada, si existe.
No parameters.
Devuelvetrueen caso de éxito,falsesi la entrada no tiene metainformación. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.
Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco, y una excepción de tipoBadMethodCallExceptionsi el acceso a escritura está deshabilitado.
Ejemplo #1 Un ejemplo dePharFileInfo::delMetaData()
<?php
try {
$a= newPhar('miphar.phar');
$a['hola'] ='hola';
var_dump($a['hola']->delMetadata());
$a['hola']->setMetadata('qué tal');
var_dump($a['hola']->delMetadata());
var_dump($a['hola']->delMetadata());
} catch (Exception $e) {
// manejar errores
}
?>El resultado del ejemplo sería:
bool(false) bool(true) bool(false)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::__destruct—Destructs a Phar entry object
Esta función no tiene parámetros.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::getCRC32—Devolver el códido CRC32 o lanzar una exepción si la CRC no ha sido verificado
Este método devuelve la suma de verificacióncrc32()del fichero dentro de un archivo Phar.
La suma de verificaicóncrc32()de un fichero dentro de un archivo Phar.
Lanza una excepción de tipoBadMethodCallExceptionsi el fichero no tiene aún su CRC32 verificado. Esto sería imposible con un uso normal, ya que la CRC es verificada al abrir el fichero para lectura o escritura.
Ejemplo #1 Un ejemplo dePharFileInfo::getCRC32()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
echo$fichero->getCRC32();
} catch (Exception $e) {
echo'Las operaciones de escritura sobre mi.phar.phar fallaron: ',$e;
}
?>El resultado del ejemplo sería:
1872820616
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::getCompressedSize—Devolver el tamaño real de un fichero (con compresión) dentro de un archivo Phar
Devuelve el tamaño del fichero dentro del archivo Phar. Los ficheros no comprimidos devolverán el mismo valor que si se utilizarafilesize()en vez defilesize()
El tamaño en bytes del fichero dentro del archivo Phar en disco.
Ejemplo #1 Un ejemplo dePharFileInfo::getCompressedSize()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
echo$fichero->getCompressedSize();
} catch (Exception $e) {
echo'Las operaciones de escritura sobre mi.phar fallaron: ',$e;
}
?>El resultado del ejemplo sería:
2
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
PharFileInfo::getContent—Get the complete file contents of the entry
This function behaves likefile_get_contents()but for Phar.
Esta función no tiene parámetros.
Returns the file contents.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::getMetadata—Devolver la metainformación específica de un fichero almacenada con un fichero
Devuelve la metainformación que fue almacenada en el manifiesto del archivo Phar para este fichero.
Cualquier variable de PHP que pueda ser serializada y almacenada como metainformación del fichero, onullsi no hay metainformación almacenada.
Ejemplo #1 Un ejemplo dePharFileInfo::getMetadata()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.txt'] ='hello';
$p['fichero.txt']->setMetadata(array('usuario'=>'bill','tipo-mime'=>'text/plain'));
var_dump($p['fichero.txt']->getMetadata());
} catch (Exception $e) {
echo'No se pudo crear y/o modificar nuevo_phar.phar:',$e;
}
?>El resultado del ejemplo sería:
array(2) {
["usuario"]=>
string(4) "bill"
["tipo-mime"]=>
string(10) "text/plain"
}
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::getPharFlags—Devolver las banderas de una entrada de fichero
Este método devuelve las banderas establecidas en el manifiesto de un Phar. Siempre devolverá0en la implementacion actual.
Las banderas del Phar (siempre0en la implementacion actual)
Ejemplo #1 Un ejemplo dePharFileInfo::getPharFlags()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->getPharFlags());
} catch (Exception $e) {
echo'No se pudo crear/modificar my.phar: ',$e;
}
?>El resultado del ejemplo sería:
int(0)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)
PharFileInfo::hasMetadata—Devolver la metainformación de una entrada
Devuelve la metainformación de una fichero dentro de un archivo phar.
No tiene parámetros.
Devuelvefalsesi no está establecida la metainformación o esnull,truesi la metainformación no esnull
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::isCRCChecked—Devolver si la entrada de fichero tiene su CRC verificada
Este método devuelve si un fichero dentro de un archivo Phar tiene su CRC verificada.
truesi el fichero tiene su CRC verificada,falsesi no.
Ejemplo #1 Un ejemplo dePharFileInfo::isCRCChecked()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->isCRCChecked());
} catch (Exception $e) {
echo'Las operaciones de creación/modificación sobre mi.phar fallaron: ',$e;
}
?>El resultado del ejemplo sería:
bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::isCompressed—Devolver si la entrada está comprimida
$compression_type= 9021976):boolEste método devuelve si un fichero está comprimido dentro de un archivo Phar con la compresión Gzip o Bzip2.
compression_typeUna de las constantesPhar::GZoPhar::BZ2, por defecto es cualquier compresión.
truesi el fichero está comprimido dentro del archivo Phar,falsesi no.
Ejemplo #1 Un ejemplo dePharFileInfo::isCompressed()
<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p['mifichero2.txt']->setCompressedGZ();
$fichero=$p['mifichero.txt'];
$fichero2=$p['mifichero2.txt'];
var_dump($fichero->isCompressed());
var_dump($fichero 2->isCompressed());
} catch (Exception $e) {
echo'La creación/modificación del phar mi.phar falló: ',$e;
}
?>El resultado del ejemplo sería:
bool(false) bool(true)
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharFileInfo::setMetadata—Establecer la metainformación específica de un fichero almacenda con un fichero
PharFileInfo::setMetadata()solamente debería usarse para almacenar información personalizada en un fichero que con pueda ser representado con la información almacenada existente con un fichero. La metainformación puede ralentizar significativamente la velocidad de carga de un archivo phar si la información es grande, o si existen muchos ficheros que contienen metainformación. Es importante observar que esos permisos de fichero están soportados nativamente dentro de un phar; es posible establecerlo con el métodoPharFileInfo::chmod(). Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.
Algunos posibles usos para la metainformación incluten pasar un usuario/grupo que debería establecerse al extraer el fichero desde el phar al disco. Otros usos podrían incluir explicitamente especificar un tipo MIME a devolver. Sin embargo, cualquier información útil que describa un fichero, excepto la que no debería estar contenida dentro del mismo, puede ser almacenada.
metadataCualquier variable de PHP que contenga información a almacenar junto a un fichero
No devuelve ningún valor.
Ejemplo #1 Un ejemplo dePharFileInfo::setMetadata()
<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.txt'] ='hola';
$p['fichero.txt']->setMetadata(array('usuario'=>'bill','tipo-mime'=>'text/plain'));
var_dump($p['fichero.txt']->getMetadata());
} catch (Exception $e) {
echo'No se pudo crear y/o modificar el phar:',$e;
}
?>El resultado del ejemplo sería:
array(2) {
["usuario"]=>
string(4) "bill"
["tipo-mime"]=>
string(10) "text/plain"
}
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
La clase PharException ofrece una excepción de clase específica de phar para bloques try/catch.
(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)
PharException—La clase PharException ofrece una excepción de clase específica de phar para bloques try/catch
Rar es un potente y eficaz archivador creado por Eugene Roshal. Esta extensión proporciona la posibilidad de leer archivos Rar, pero no soporta la escritura de los mismos, ya que no es compatible con la biblioteca UnRar y está directamente prohibido por su licencia.
Se puede encontrar más información sobre Rar y UnRar en» http://www.rarlabs.com/.
No se requiere de ninguna biblioteca externa para compilar esta extensión.
Rar está actualmente disponible a través de PECL» https://pecl.php.net/package/rar.
También puede usar el instalador PECL para instalar la extensión Rar, utilizando el siguiente comando:pecl -v install rar.
Siempre puede descargar el paquetetar.gze instalar Rar a mano:
Ejemplo #1 Instalación Rar
gunzip rar-xxx.tgz tar -xvf rar-xxx.tar cd rar-xxx phpize ./configure && make && make install
Los usuarios de Windows habilitaránphp_rar.dllen el interior dephp.inicon el fin de utilizar estas funciones. Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Esta extensión registra tres clases internas: Las representaciones de archivo devuelto porrar_open()–RarArchive–, las representaciones de entrada devuelto porrar_list()yrar_entry_get()–RarEntryy el tipo de excepciónRarException.
Esta extensión también registra un recurso de secuencia, llamado "rar" y una envoltura URL llamada "envoltura rar" y registrada bajo el prefijo "rar".
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
RAR_HOST_MSDOS(integer)RarEntry::HOST_MSDOSen su lugar.RAR_HOST_OS2(integer)RarEntry::HOST_OS2en su lugar.RAR_HOST_WIN32(integer)RarEntry::HOST_WIN32en su lugar.RAR_HOST_UNIX(integer)RarEntry::HOST_UNIXen su lugar.RAR_HOST_BEOS(integer)RarEntry::HOST_BEOSen su lugar.Ver tambiénrar://.
Ejemplo #1 Descompresión "al vuelo"
<?php
if (!array_key_exists("i",$_GET) || !is_numeric($_GET["i"]))
die("Index unspecified or non-numeric");
$index= (int)$_GET["i"];
$arch=RarArchive::open("example.rar");
if ($arch===FALSE)
die("Cannot open example.rar");
$entries=$arch->getEntries();
if ($entries===FALSE)
die("Cannot retrieve entries");
if (!array_key_exists($index,$entries))
die("No such index:$index");
$orfilename=$entries[$index]->getName();//UTF-8 encoded
$filesize=$entries[$index]->getUnpackedSize();
/* you could check HTTP_IF_MODIFIED_SINCE here and compare with
* $entries[$index]->getFileTime(). You could also send a
* "Last modified" header */
$fp=$entries[$index]->getStream();
if ($fp===FALSE)
die("Cannot open file with index$indexinsided the archive.");
$arch->close();//no longer needed; stream is independent
functiondetectUserAgent() {
if (!array_key_exists('HTTP_USER_AGENT',$_SERVER))
return"Other";
$uas=$_SERVER['HTTP_USER_AGENT'];
if (preg_match("@Opera/@",$uas))
return"Opera";
if (preg_match("@Firefox/@",$uas))
return"Firefox";
if (preg_match("@Chrome/@",$uas))
return"Chrome";
if (preg_match("@MSIE ([0-9.]+);@",$uas,$matches)) {
if (((float)$matches[1]) >=7.0)
return"IE";
}
return"Other";
}
/*
* We have 3 options:
* - For FF and Opera, which support RFC 2231, use that format.
* - For IE and Chrome, use attwithfnrawpctenclong
* (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
* - For the others, convert to ISO-8859-1, if possible
*/
$formatRFC2231='Content-Disposition: attachment; filename*=UTF-8\'\'%s';
$formatDef='Content-Disposition: attachment; filename="%s"';
switch (detectUserAgent()) {
case"Opera":
case"Firefox":
$orfilename=rawurlencode($orfilename);
$format=$formatRFC2231;
break;
case"IE":
case"Chrome":
$orfilename=rawurlencode($orfilename);
$format=$formatDef;
break;
default:
if (function_exists('iconv'))
$orfilename=
@iconv("UTF-8","ISO-8859-1//TRANSLIT",$orfilename);
$format=$formatDef;
}
header(sprintf($format,$orfilename));
//cannot send error messages from now on (headers already sent)
//replace by real content type, perhaps infering from the file extension
$contentType="application/octet-stream";
header("Content-Type:$contentType");
header("Content-Transfer-Encoding: binary");
header("Content-Length:$filesize");
if ($_SERVER['REQUEST_METHOD'] =="HEAD")
die();
while (!feof($fp)) {
$s= @fread($fp,8192);
if ($s===false)
break;//useless to send error messages
echo$s;
}
?>En este ejemplo se obtiene el archivo que contiene el archivo RAR y se ofrece para descargar.
Ejemplo #2 Ejemplo de sistema de extracción de archivos Rar
<?php
$rar_file=rar_open('example.rar') or die("Can't open Rar archive");
$entries=rar_list($rar_file);
foreach ($entriesas$entry) {
echo'Filename: '.$entry->getName() ."\n";
echo'Packed size: '.$entry->getPackedSize() ."\n";
echo'Unpacked size: '.$entry->getUnpackedSize() ."\n";
$entry->extract('/dir/extract/to/');
}
rar_close($rar_file);
?>Este ejemplo extrae cada archivo del archivo Rar en el directorio especificado.
(PECL rar >= 3.0.0)
rar_wrapper_cache_stats—Caché de aciertos y errores del URL wrapper
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
Esta función no tiene parámetros.
(PECL rar >= 2.0.0)
Esta clase representa un archivo RAR que puede estar formado por varios volúmenes (partes) y que contiene una serie de entradas RAR (por ejemplo: archivos, directorios y otros objetos especiales, como enlaces simbólicos).
Los objetos de esta clase puede ser atravesado, dando las entradas almacenadas en el archivo RAR respectivamente. Estas entradas también pueden ser obtenidas medianteRarArchive::getEntry()yRarArchive::getEntries().
(PECL rar >= 2.0.0)
RarArchive::close--rar_close—Cerrar archivo RAR y liberar todos los recursos
Estilo orientado a objetos (método):
Estilo por procedimientos:
Cerar archivo RAR y liberar todos los recursos asignados.
rarfileUn objetoRarArchive, abierto conrar_open().
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 2.0.0 | Las entradas RAR devueltas porRarArchive::getEntry()yRarArchive::getEntries()son ahora invalidadas cuando se llama a este método. Esto significa que todos los métodos de instancia llamados por tales entradas y no garantizan el éxito. |
Ejemplo #1 Estilo orientado a objetos
<?php
$rar_arch=RarArchive::open('latest_winrar.rar');
echo$rar_arch."\n";
$rar_arch->close();
echo$rar_arch."\n";
?>El resultado del ejemplo sería algo similar a:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
Ejemplo #2 Estilo por procedimientos
<?php
$rar_arch=rar_open('latest_winrar.rar');
echo$rar_arch."\n";
rar_close($rar_arch);
echo$rar_arch."\n";
?>(PECL rar >= 2.0.0)
RarArchive::getComment--rar_comment_get—Obtener comentarios de texto desde el archivo RAR
Estilo orientado a objetos (method):
Estilo por procedimientos:
Obtener (global) comentario almacenado en el archivo RAR. Este puede ser de hasta 64 KiB de longitud.
Nota:
Esta extensión no es compatible con los comentarios en el nivel de entrada.
rarfileUn objetoRarArchive, abierto conrar_open().
Devuelve el comentario onullsi no hay ninguno.
Nota:
RAR no tiene actualmente soporte para comentarios unicode. La codificación de los resultados de esta función no es especificado, pero esta debe ser probablemente Windows-1252.
Ejemplo #1 Estilo orientado a objetos
<?php
$rar_arch=RarArchive::open('commented.rar');
echo$rar_arch->getComment();
?>El resultado del ejemplo sería algo similar a:
This is the comment of the file commented.rar.
Ejemplo #2 Estilo por procedimientos
<?php
$rar_arch=rar_open('commented.rar');
echorar_comment_get($rar_arch);
?>(PECL rar >= 2.0.0)
RarArchive::getEntries--rar_list—Obtener la lista completa de entradas del archivo RAR
Estilo orientado a objetos (método):
Estilo por procedimientos:
Obtener la lista de entradas (archivos y directorios) de el archivo RAR.
Nota:
Si el archivo tiene entradas con el mismo nombre, este método, junto conRarArchive
foreachiteraciona y otorga un acceso array-like con índices numéricos, únicos para acceder a todas las entradas (por ejemplo,RarArchive::getEntry()y elrar://wrapperson insuficientes).
rarfileUn objetoRarArchive, abierto conrar_open().
rar_list()devuelve array de objetosRarEntryofalseen caso de error.
| Versión | Descripción |
|---|---|
| 3.0.0 | Soporte para archivos RAR con nombres entrada repetidos que ya no produce deficiencias. |
Ejemplo #1 Estilo orientado a objetos
<?php
$rar_arch=RarArchive::open('solid.rar');
if ($rar_arch===FALSE)
die("Could not open RAR archive.");
$rar_entries=$rar_arch->getEntries();
if ($rar_entries===FALSE)
die("Could retrieve entries.");
echo"Found ".count($rar_entries) ." entries.\n";
foreach ($rar_entriesas$e) {
echo$e;
echo"\n";
}
$rar_arch->close();
?>El resultado del ejemplo sería algo similar a:
Found 2 entries. RarEntry for file "tese.txt" (23b93a7a) RarEntry for file "unrardll.txt" (2ed64b6e)
Ejemplo #2 Estilo por procedimientos
<?php
$rar_arch=rar_open('solid.rar');
if ($rar_arch===FALSE)
die("Could not open RAR archive.");
$rar_entries=rar_list($rar_arch);
if ($rar_entries===FALSE)
die("Could retrieve entries.");
echo"Found ".count($rar_entries) ." entries.\n";
foreach ($rar_entriesas$e) {
echo$e;
echo"\n";
}
rar_close($rar_arch);
?>rar://wrapper(PECL rar >= 2.0.0)
RarArchive::getEntry--rar_entry_get—Obtener el objeto entrada desde el archivo RAR
Estilo orientado a objetos (método):
Estilo por procedimientos:
Obtener el objeto entrada (archivo o directorio) desde el archivo RAR.
Nota:
También puede obtener objetos de entrada utilizandoRarArchive::getEntries().
Tenga en cuenta que un archivo RAR puede tener varias entradas con el mismo nombre; este método recuperará sólo el primero.
rarfileUn objetoRarArchive, abierto conrar_open().
entrynameRuta a la entrada dentro del archivo RAR.
Nota:
La ruta debe ser la misma devuelta porRarEntry::getName().
Devuelve el objetoRarEntryencontrado ofalseen caso de error.
Ejemplo #1 Estilo orientado a objetos
<?php
$rar_arch=RarArchive::open('solid.rar');
if ($rar_arch===FALSE)
die("Could not open RAR archive.");
$rar_entry=$rar_arch->getEntry('tese.txt');
if ($rar_entry===FALSE)
die("Could get such entry");
echoget_class($rar_entry)."\n";
echo$rar_entry;
$rar_arch->close();
?>El resultado del ejemplo sería algo similar a:
RarEntry RarEntry for file "tese.txt" (23b93a7a)
Ejemplo #2 Estilo por procedimientos
<?php
$rar_arch=rar_open('solid.rar');
if ($rar_arch===FALSE)
die("Could not open RAR archive.");
$rar_entry=rar_entry_get($rar_arch,'tese.txt');
if ($rar_entry===FALSE)
die("Could get such entry");
echoget_class($rar_entry)."\n";
echo$rar_entry;
rar_close($rar_arch);
?>rar://wrapper(PECL rar >= 3.0.0)
RarArchive::isBroken--rar_broken_is—Comprobar si un archivo está dañado (incompleto)
Estilo orientado a objetos (método):
Estilo por procedimientos:
Esta función determina si un archivo está incompleto, por ejemplo, Si un volumen no se encuentra o un volumen está truncado.
rarfileUn objetoRarArchive, abierto conrar_open().
Devuelvetruesi el archivo está dañado,falseen caso contrario. Esta función puede también devolverfalsesi el archivo pasado fue cerrado. La única manera para poder distinguir aparte ambos casos es habilitando y permitiendo excepciones conRarException::setUsingExceptions(); sin embargo, esto debería ser innecesario, ya que un programa no debe funcionar con archivos cerrados.
Ejemplo #1 Estilo orientado a objetos
<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento es utilizado para omitir avisos */
$arch=RarArchive::open($file,null,'retnull');
var_dump($arch->isBroken());
?>El resultado del ejemplo sería algo similar a:
bool(true)
Ejemplo #2 Estilo por procedimientos
<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento es utilizado para omitir avisos */
$arch=rar_open($file,null,'retnull');
var_dump(rar_broken_is($arch));
?>(PECL rar >= 2.0.0)
RarArchive::isSolid--rar_solid_is—Comprueba si el archivo RAR es sólido
Estilo orientado a objetos (método):
Estilo por procedimientos:
Comprueba si el archivo RAR es sólido. La extracción individual de ficheros es más lenta en archivos sólidos.
rarfileLa instancia delRarArchive, abierto conrar_open().
Devuelvetruesi el archivo es sólido, de lo contrario retornafalse.
Ejemplo #1 Estilo orientado a objetos
<?php
$arch1=RarArchive::open("store_method.rar");
$arch2=RarArchive::open("solid.rar");
echo"$arch1: ". ($arch1->isSolid()?'yes':'no') ."\n";
echo"$arch2: ". ($arch2->isSolid()?'yes':'no') ."\n";
?>El resultado del ejemplo sería algo similar a:
RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes
Ejemplo #2 Estilo por procedimientos
<?php
$arch1=rar_open("store_method.rar");
$arch2=rar_open("solid.rar");
echo"$arch1: ". (rar_solid_is($arch1)?'yes':'no') ."\n";
echo"$arch2: ". (rar_solid_is($arch2)?'yes':'no') ."\n";
?>(PECL rar >= 2.0.0)
RarArchive::open--rar_open—Abre un archivo RAR
Estilo orientado a objetos (método):
$filename,string$password= NULL,callable$volume_callback= NULL):RarArchiveEstilo por procedimientos:
Abre un archivo RAR especificado y devuelve la instanciaRarArchiveque lo representa.
Nota:
Si el archivo a abrir esta dividido en volúmenes, se deberá pasar la ruta del primer volúmen como parámetro de la función. De lo contrario, no todos los archivos se mostraran.
filenameRuta del archivo Rar.
passwordContraseña en texto plano, si fuera necesario descifrar la cabecera del archivo. También se utilizará por defecto si hay archivos encriptados encontrados. Tenga en cuenta que los archivos pueden poseer diferentes contraseñas en cuanto a las cabeceras y entre ellos.
volume_callbackUna función que recibe como parámetro la ruta del volúmen que no fue encontrado y retorna una cadena con la ruta correcta para dicho archivo onullsi el volúmen no existe o no es conocido. El programador debería asegurar que la función pasada no cause bucles, ya que esta función es llamada repetidas veces si la ruta devuelta en una llamada previa no corresponde con el volúmen solicitado. Especificando este parámetro se omite la notice que se emitiría cuando un volúmen no es encontrado; una implementación que solo devuelvanullpuede, por lo tanto, utilizarce para omitir dichos notices.
En versiones menores a 2.0.0 de PHP, esta función no manejaria rutas relativas correctamente. Userealpath()como una solución.
Devuelve una instancia delRarArchivesolicitado ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 3.0.0 | volume_callbackfue agregada. |
Ejemplo #1 Estilo orientado a objetos
<?php
$rar_arch=RarArchive::open('encrypted_headers.rar','samplepassword');
if ($rar_arch===FALSE)
die("Failed opening file");
$entries=$rar_arch->getEntries();
if ($entries===FALSE)
die("Failed fetching entries");
echo"Found ".count($entries) ." files.\n";
if (empty($entries))
die("No valid entries found.");
$stream=reset($entries)->getStream();
if ($stream===FALSE)
die("Failed opening first file");
$rar_arch->close();
echo"Content of first one follows:\n";
echostream_get_contents($stream);
fclose($stream);
?>El resultado del ejemplo sería algo similar a:
Found 2 files. Content of first one follows: Encrypted file 1 contents.
Ejemplo #2 Estilo por procedimientos
<?php
$rar_arch=rar_open('encrypted_headers.rar','samplepassword');
if ($rar_arch===FALSE)
die("Failed opening file");
$entries=rar_list($rar_arch);
if ($entries===FALSE)
die("Failed fetching entries");
echo"Found ".count($entries) ." files.\n";
if (empty($entries))
die("No valid entries found.");
$stream=reset($entries)->getStream();
if ($stream===FALSE)
die("Failed opening first file");
rar_close($rar_arch);
echo"Content of first one follows:\n";
echostream_get_contents($stream);
fclose($stream);
?>Ejemplo #3 Volume Callback
<?php
/* En este ejemplo, hay un volúmen llamdo multi_broken.part1.rar
* cuyo próximo volúmen es llamado multi.part2.rar */
functionresolve($vol) {
if (preg_match('/_broken/',$vol))
returnstr_replace('_broken','',$vol);
else
returnnull;
}
$rar_file1=rar_open(dirname(__FILE__).'/multi_broken.part1.rar',null,'resolve');
$entry=$rar_file1->getEntry('file2.txt');
$entry->extract(null,dirname(__FILE__) ."/temp_file2.txt");
?>(PECL rar >= 3.0.0)
RarArchive::setAllowBroken—Determina si la apertura de archivos dañados se permite
Estilo orientado a objetos (method):
$allow_broken):boolEstilo por procedimientos:
Este método determina si los archivos dañados pueden ser leidos o todas las operaciones que intenten extraer el archivo de las entradas producirán un error. Los archivos rotos son archivos para los cuales ningún error es detectado cuando el archivo es abierto pero un error se produce cuando leemos las entradas.
rarfileUn objetoRarArchive, abierto conrar_open().
allow_brokenDetermina si se permite la lectura de archivos dañados (true) o no (false).
Devuelvetrueofalseen caso de error. Sólo se producirá un error si el archivo ya fue cerrado.
Ejemplo #1 Estilo orientado a objetos
<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento omite el mensaje "volumen no encontrado" */
$a=RarArchive::open($file,null,'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as$e) {
echo"$e\n";
}
var_dump(count($a));
?>El resultado del ejemplo sería algo similar a:
RarEntry for file "file1.txt" (52b28202) int(1)
Ejemplo #2 Estilo por procedimientos
<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento omite el mensaje "volumen no encontrado" */
$a=rar_open($file,null,'retnull');
rar_allow_broken_set($a,true);
foreach (rar_list($a) as$e) {
echo"$e\n";
}
var_dump(count($a));
?>(PECL rar >= 2.0.0)
RarArchive::__toString—Obtener representación de texto
Proporciona una representación de cadena para este objetoRarArchive. Esta actualmente muestra la ruta completa del volumen de archivo que fue abierto y si el recurso es válido o ya estaba cerrado a través de una llamada aRarArchive::close().
Este método debe ser utilizado sólo para propósitos de depuración, ya que no existen garantías en cuanto a la información que contiene el resultado o cómo esta es formateada.
Esta función no tiene parámetros.
Una representación textual de este objetoRarArchive. El contenido de esta representación no es especificado.
Ejemplo #1 Ejemplo deRarArchive::__toString()
<?php
$rar_arch=RarArchive::open('latest_winrar.rar');
echo$rar_arch."\n";
$rar_arch->close();
echo$rar_arch."\n";
?>El resultado del ejemplo sería algo similar a:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
(PECL rar >= 0.1)
Una entrada RAR, representa un directorio o un archivo comprimido dentro de un archivo RAR.
$dir,$filepath= "",$password= NULL,$extended_data= falseRarEntry::HOST_MSDOSSi el valor devuelto porRarEntry::getHostOs()es igual a esta constante, MS-DOS fue utilizado para añadir esta entrada. Utilizar en lugar deRAR_HOST_MSDOS.
RarEntry::HOST_OS2Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, OS/2 fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_OS2.
RarEntry::HOST_WIN32Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, Microsoft Windows fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_WIN32.
RarEntry::HOST_UNIXSi el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo UNIX no especificado fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_UNIX.
RarEntry::HOST_MACOSSi el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo Mac fue utilizado para añadir esta entrada.
RarEntry::HOST_BEOSSi el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo BeOS fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_BEOS.
RarEntry::ATTRIBUTE_WIN_READONLYBit que representa una entrada de Windows con un atributo de sólo lectura. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
Bit que representa una entrada de Windows con un atributo oculto. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_SYSTEMBits que representa una entrada de Windows con un atributo del sistema. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_DIRECTORYBit que representa una entrada de Windows con un atributo de directorio (entrada es un directorio). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.
RarEntry::ATTRIBUTE_WIN_ARCHIVEBit que representa una entrada de Windows con un atributo de archivo. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_DEVICEBit que representa una entrada de Windows con un atributo de dispositivo. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_NORMALBit que representa una entrada de Windows con un atributo de archivo normal (entrada NO es un directorio). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.
RarEntry::ATTRIBUTE_WIN_TEMPORARYBit que representa una entrada de Windows con un atributo temporal. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_SPARSE_FILEBit que representa una entrada de Windows con un atributo de archivo disperso (archivo es un archivo disperso NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_REPARSE_POINTBit que representa una entrada de Windows con un atributo punto de re-análisis (entrada es un punto de re-análisis NTFS, por ejemplo, un directorio enlace o un sistema de montaje de archivos). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_COMPRESSEDBit que representa una entrada de Windows con un atributo comprimido (sólo NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_OFFLINEBit que representa una entrada de Windows con un atributo fuera de línea (entrada es desconectada y no accesible). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXEDBit que representa una entrada de Windows con un atributo de contenido no indexado (entrada deberá ser indexada). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_ENCRYPTEDBit que representa una entrada de Windows con un atributo cifrado (sólo NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_WIN_VIRTUALBit que representa una entrada de Windows con un atributo virtual. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.
RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTEBit que representa una entrada que es ejecutable en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_WORLD_WRITEBit que representa una entrada que es escribible en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_WORLD_READBit que representa una entrada que es leible en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTEBit que representa una entrada UNIX que es grupo ejecutable. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_GROUP_WRITEBit que representa una entrada UNIX que es grupo escribible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_GROUP_READBit que representa una entrada UNIX que es grupo leible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTEBit que representa una entrada UNIX que es propietario ejecutable. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_OWNER_WRITEBit que representa una entrada UNIX que es propietario escribible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_OWNER_READBit que representa una entrada UNIX que es propietario leible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_STICKYBit que representa el sticky bit UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_SETGIDBit que representa el atributo UNIX setgid. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_SETUIDBit que representa el atributo UNIX setuid. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTETMáscara para aislar a los últimos cuatro bits (nibble) de atributos UNIX (_S_IFMT, el tipo de máscara de archivo). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con las constantesRarEntry::ATTRIBUTE_UNIX_FIFO,RarEntry::ATTRIBUTE_UNIX_CHAR_DEV,RarEntry::ATTRIBUTE_UNIX_DIRECTORY,RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV,RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE,RarEntry::ATTRIBUTE_UNIX_SYM_LINKandRarEntry::ATTRIBUTE_UNIX_SOCKET.
RarEntry::ATTRIBUTE_UNIX_FIFOFIFOs Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::ATTRIBUTE_UNIX_CHAR_DEVDispositivo de tipo carácter Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::ATTRIBUTE_UNIX_DIRECTORYDirectorios Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que fueron añadidas en otros sistemas operativos.
RarEntry::ATTRIBUTE_UNIX_BLOCK_DEVDispositivo de tipo bloque Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::ATTRIBUTE_UNIX_REGULAR_FILEArchivos regular Unix (no directorios) tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. Véase tambiénRarEntry::isDirectory(), ue también trabaja con entradas que fueron añadidas en otros sistemas operativos.
RarEntry::ATTRIBUTE_UNIX_SYM_LINKEnlace simbólico Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::ATTRIBUTE_UNIX_SOCKETSockets Unix will tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
(PECL rar >= 0.1)
RarEntry::extract—Extraer entrada del archivo
$dir,$filepath= "",$password= NULL,$extended_data= falseRarEntry::extract()extrae los datos de entrada. Esto creará un nuevo archivo en eldirespecificado con el mismo nombre que el nombre de la entrada, a menos que el segundo argumento sea especificado. Siga leyendo más abajo para obtener mayor información.
dirRuta al directorio donde los archivos deben ser extraídos. Este parámetro es considerado si y sólo si no esfilepath. Si ambos parámetros están vacíos se intentará una extracción en el directorio actual.
filepathRuta (relativa o absoluta) que contiene el directorio y el nombre del archivo extraído. Este parámetro anula los parámetrosdiry el nombre del archivo original.
passwordLa contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si se omite este parámetro y la entrada está cifrada, la contraseña dada arar_open(), será utlizada. Si una contraseña incorrecta es dada, de forma explicita o implicita viarar_open(), la comprobación CRC fallará y este método fallará y devolveráfalse. Si no se da la contraseña y se requiere una, este método fallará y devolveráfalse. Puede comprobar si una entrada está cifrada conRarEntry::isEncrypted().
extended_dataSitrue, información extendida tales como NTFS ACLs e información propietaria Unix será establecida en los archivos extraidos, siempre que esta esté presente en el archivo.
Antes de la versión 2.0.0, esta función no manejaba las rutas relativas correctamente. Utilicerealpath()como una solución.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 3.0.0 | extended_datafue añadido. |
| 3.0.0 | Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso |
Ejemplo #1 Ejemplo deRarEntry::extract()
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
$entry->extract('/dir/to');// crear /dir/to/Dir/file.txt
$entry->extract(false,'/dir/to/new_name.txt');// crear /dir/to/new_name.txt
?>Ejemplo #2 ¿Cómo extraer todos los archivos en archivo?:
<?php
/* ejemplo por Erik Jenssen también conocido como erix */
$filename="foobar.rar";
$filepath="/home/foo/bar/";
$rar_file=rar_open($filepath.$filename);
$list=rar_list($rar_file);
foreach($listas$file) {
$entry=rar_entry_get($rar_file,$file);
$entry->extract(".");// extraer el directorio actual
}
rar_close($rar_file);
?>rar://wrapper(PECL rar >= 0.1)
RarEntry::getAttr—Obtener los atributos de la entrada
Devuelve los atributos dependientes del SO del archivo de entrada.
Esta función no tiene parámetros.
Devuelve los atributos ofalseen caso de error.
Ejemplo #1 Ejemplo deRarEntry::getAttr()
<?php
$rar_file=rar_open('example.rar') or die("Can't open Rar archive");
$entry=rar_entry_get($rar_file,'dir/in/the/archive') or die("Can't find such entry");
$host_os=$entry->getHostOs();
$attr=$entry->getAttr();
switch($host_os) {
caseRAR_HOST_MSDOS:
caseRAR_HOST_OS2:
caseRAR_HOST_WIN32:
caseRAR_HOST_MACOS:
printf("%c%c%c%c%c%c\n",
($attr&0x08) ?'V':'.',
($attr&0x10) ?'D':'.',
($attr&0x01) ?'R':'.',
($attr&0x02) ?'H':'.',
($attr&0x04) ?'S':'.',
($attr&0x20) ?'A':'.');
break;
caseRAR_HOST_UNIX:
caseRAR_HOST_BEOS:
switch ($attr&0xF000)
{
case0x4000:
printf("d");
break;
case0xA000:
printf("l");
break;
default:
printf("-");
break;
}
printf("%c%c%c%c%c%c%c%c%c\n",
($attr&0x0100) ?'r':'-',
($attr&0x0080) ?'w':'-',
($attr&0x0040) ? (($attr&0x0800) ?'s':'x'):(($attr&0x0800) ?'S':'-'),
($attr&0x0020) ?'r':'-',
($attr&0x0010) ?'w':'-',
($attr&0x0008) ? (($attr&0x0400) ?'s':'x'):(($attr&0x0400) ?'S':'-'),
($attr&0x0004) ?'r':'-',
($attr&0x0002) ?'w':'-',
($attr&0x0001) ?'x':'-');
break;
}
rar_close($rar_file);
?>(PECL rar >= 0.1)
RarEntry::getCrc—Obtener el CRC de la entrada
Devuelve una cadena hexadecimal representación de el CRC del archivo de entrada.
Esta función no tiene parámetros.
Devuelve el CRC del archivo de entrada ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 2.0.0 | Este método devuelve ahora valores correctos para archivos de varios volúmenes. |
(PECL rar >= 0.1)
RarEntry::getFileTime—Devolver entrada última fecha de modificación
Devuelve entrada última fecha modificación.
Esta función no tiene parámetros.
Devuelve entrada última fecha de modificación como una cadena en formatoYYYY-MM-DD HH:II:SS, ofalseen caso de error.
(PECL rar >= 0.1)
RarEntry::getHostOs—Obtener sistema operativo anfitrión del archivo de entrada
Devuelve el código del sistema operativo anfitrión del archivo de entrada.
Esta función no tiene parámetros.
Devuelve el código del sistema operativo anfitrión, ofalseen caso de error.
Ejemplo #1 Ejemplo deRarEntry::getHostOs()(version >= 2.0.0)
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
caseRarEntry::HOST_MSDOS:
echo"MS-DOS\n";
break;
caseRarEntry::HOST_OS2:
echo"OS2\n";
break;
caseRarEntry::HOST_WIN32:
echo"Win32\n";
break;
caseRarEntry::HOST_MACOS:
echo"MacOS\n";
break;
caseRarEntry::HOST_UNIX:
echo"Unix/Linux\n";
break;
caseRarEntry::HOST_BEOS:
echo"BeOS\n";
break;
}
?>Ejemplo #2RarEntry::getHostOs()example (version <= 1.0.0)
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
caseRAR_HOST_MSDOS:
echo"MS-DOS\n";
break;
caseRAR_HOST_OS2:
echo"OS2\n";
break;
caseRAR_HOST_WIN32:
echo"Win32\n";
break;
caseRAR_HOST_MACOS:
echo"MacOS\n";
break;
caseRAR_HOST_UNIX:
echo"Unix/Linux\n";
break;
caseRAR_HOST_BEOS:
echo"BeOS\n";
break;
}
?>(PECL rar >= 0.1)
RarEntry::getMethod—Obtener método pack de la entrada
RarEntry::getMethod()devuelve el número del método utilizado cuando añadimos archivo actual de entrada.
Esta función no tiene parámetros.
Devuelve el número de método ofalseen caso de error.
Ejemplo #1 Ejemplo deRarEntry::getMethod()
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
echo"Method number: ".$entry->getMethod();
?>(PECL rar >= 0.1)
RarEntry::getName—Obtener el nombre de la entrada
Devuelve el nombre (con la ruta) de el archivo entrada.
Esta función no tiene parámetros.
Devuelve el nombre de la entrada como una cadena, ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 2.0.0 | Desde la versión 2.0.0, la cadena devuelta está codificada en Unicode/UTF-8. |
Ejemplo #1 Ejemplo deRarEntry::getName()
<?php
//este ejemplo, es seguro, incluso en páginas no codificados en UTF-8
//para esa codificación en UTF-8, la llamada a mb_convert_encoding es innecesaria.
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
echo"Entry name: ".mb_convert_encoding(
htmlentities(
$entry->getName(),
ENT_COMPAT,
"UTF-8"
),
"HTML-ENTITIES",
"UTF-8"
);
?>(PECL rar >= 0.1)
RarEntry::getPackedSize—Obtiene el tamaño empaquetado de la entrada
Obtiene el tamaño empaquetado del archivo entrada.
Nota:
Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devuelto está limitado a 2 GB. Compruebe la constante
PHP_INT_MAX.
Esta función no tiene parámetros.
Devuelve el tamaño empaquetado, ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 2.0.0 | Este método devuelve ahora los valores correctos de empaquetado mayores a 2 GB en plataformas de 64-bitintegers y nunca devuelve valores negativos en otras plataformas. |
Ejemplo #1 Ejemplo deRarEntry::getPackedSize()
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
echo"Packed size of ".$entry->getName() ." = ".$entry->getPackedSize() ." bytes";
?>(PECL rar >= 2.0.0)
RarEntry::getStream—Obtener manejador de archivo para entrada
$password= ?):resourceDevuelve un manejador de archivo que soporta operaciones de lectura. Este manejador proporciona descompresión al vuelo para esta entrada.
El manejador no es invalidado por llamar arar_close().
El flujo resultante no tiene verificación de integridad. En particular, archivo corrupto y descifrado con una clave errónea, no será detectado. Es responsabilidad del programador utilizar la entrada CRC para comprobar la integridad, si así lo desea.
passwordLa contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si el parámetro es omitido y la entrada está cifrada, la contraseña dada arar_open(), será utilizada. Si una contraseña incorrecta es dada, ya sea explícita o implícitamente viarar_open(), teste método resultante de flujo producirá error de salida. Si no se especifica la contraseña y se requiere una, este método fallará y devolveráfalse. Puede comprobar si una entrada está cifrada conRarEntry::isEncrypted().
El manejador de archivo ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 3.0.0 | Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso. |
Ejemplo #1 Ejemplo deRarEntry::getStream()
<?php
$rar_file=rar_open('example.rar');
if ($rar_file===false)
die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt');
if ($entry===false)
die("Failed to find such entry");
$stream=$entry->getStream();
if ($stream===false)
die("Failed to obtain stream.");
rar_close($rar_file);//flujo es independiente de archivo
while (!feof($stream)) {
$buff=fread($stream,8192);
if ($buff!==false)
echo$buff;
else
break;//error fread
}
fclose($stream);
?>rar://wrapper(PECL rar >= 0.1)
RarEntry::getUnpackedSize—Obtener el tamaño descomprimido de la entrada
Obtiene el tamaño descomprimido del archivo entrada.
Nota:
Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devueltos está limitado a 2 GB. Compruebe la constante
PHP_INT_MAX.
Esta función no tiene parámetros.
Devuelve el tamaño descomprimido, ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 2.0.0 | Este método devuelve ahora valores correctos de tamaño descomprimido superiores a 2 GB en plataformas con 64-bitintegers y nunca devuelve valores negativos en otras plataformas. |
Ejemplo #1 Ejemplo deRarEntry::getUnpackedSize()
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
echo"Unpacked size of ".$entry->getName() ." = ".$entry->getPackedSize() ." bytes";
?>(PECL rar >= 0.1)
RarEntry::getVersion—Obtener la versión mínima del programa RAR requerida para desempaquetar la entrada
Devuelve la versión mínima del programa RAR (por ejemplo WinRAR) requerida para desempaquetar la entrada. Esta es codificada como 10 * version mayor + versión menor.
Esta función no tiene parámetros.
Devuelve la versión ofalseen caso de error.
Ejemplo #1 Ejemplo deRarEntry::getVersion()
<?php
$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");
$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");
echo"Rar version required for unpacking: ".$entry->getVersion();
?>(PECL rar >= 2.0.0)
RarEntry::isDirectory—Comprobar si una entrada representa un directorio
Comprueba si una entrada representa un directorio.
Esta función no tiene parámetros.
Devuelvetruesi la entrada es un directorio yfalseen caso contrario.
Esta función sólo está disponible desde la versión 2.0.0, pero también puede comprobarse si una entrada es un directorio mediante la comprobación de los atributos de entrada, así (sólo funciona para los archivos comprimidos en RAR por Windows o Unix):
<?php
//...
//Abrir archivo, obtener la entrada y almacenarla en la variable $e...
//...
$isDirectory= (bool) ((($e->getHostOs() ==RAR_HOST_WIN32) && ($e->getAttr() &0x10)) ||
(($e->getHostOs() ==RAR_HOST_UNIX) && (($e->getAttr() &0xf000) ==0x4000)));
?>(PECL rar >= 2.0.0)
RarEntry::isEncrypted—Comprobar si una entrada está cifrada
Comprueba si el contenido de la entrada actual está cifrado.
Nota:
La contraseña utilizada puede variar entre los archivos dentro del mismo archivo RAR.
Esta función no tiene parámetros.
Devuelvetruesi la entrada actual se encuentra cifrada yfalseen caso contrario.
(PECL rar >= 2.0.0)
RarEntry::__toString—Obtener texto representación de entrada
RarEntry::__toString()devuelve una representación textual de esta entrada. Esta incluye si la entrada es un archivo o un directorio (enlaces simbólicos y otros objetos especiales serán tratados como archivos), el nombre UTF-8 de la entrada y su CRC. La forma y el contenido de esta representación puede cambiar en el futuro, así que no son fiables.
Esta función no tiene parámetros.
Una representación textual de la entrada.
(PECL rar >= 2.0.0)
Esta clase sirve para dos propósitos: estas son el tipo de las excepciones lanzadas por la extensión RAR funciones y métodos y esto permite, a través de métodos estáticos consultar y definir el error y el comportamiento de la extensión, por ejemplo, si las excepciones son lanzadas o solamente se emiten advertencias.
Los códigos de error que se utilizan los siguientes:
(PECL rar >= 2.0.0)
RarException::isUsingExceptions—Comprobar si el manejador de errores con excepciones está en uso
Comprueba si las funciones RAR emitirán avisos y devolverán valores de error o si ellas lanzarán excepciones en la mayoría de las circunstancias (no incluye algunos errores de programación tales como pasar el tipo incorrecto de argumento).
Esta función no tiene parámetros.
Devuelvetruesi las excepciones estan siendo utilizadas,falseen caso contrario.
Ejemplo #1 Ejemplo deRarException::isUsingExceptions()
<?php
//El valor predeterminado es no usar excepciones
var_dump(RarException::isUsingExceptions());
?>El resultado del ejemplo sería algo similar a:
bool(false)
(PECL rar >= 2.0.0)
RarException::setUsingExceptions—Activar y desactivar el manejador de errores con excepciones
$using_exceptions):voidSi y sólo si el argumento estrue, entonces, en lugar de emitir advertencias y devolver un valor especial indicando error cuando la biblioteca UnRAR encuentre un error, una excepción de tipoRarExceptionserá lanzada.
Las excepciones también será lanzado para los siguientes errores, que se producen fuera de la biblioteca (su código de error será -1):
using_exceptionsDebe sertruepara activar lanzamiento de excepciones,falsepara descativarlo (el valor por defecto).
Ejemplo #1 Ejemplo deRarException::setUsingExceptions()
<?php
var_dump(RarException::isUsingExceptions());
$arch=RarArchive::open("does_not_exist.rar");
var_dump($arch);
RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch=RarArchive::open("does_not_exist.rar");
var_dump($arch);//not reached
?>El resultado del ejemplo sería algo similar a:
bool(false)
Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)
Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
thrown in C:\php_rar\trunk\tests\test.php on line 8
Esta extensión permite leer o escribir de forma transparente archivos comprimidos ZIP y los ficheros que hay dentro.
Esta extensión usa las funciones de» zlibpor Jean-loup Gailly y Mark Adler.
Para poder utilizar estas funciones, se debe compilar PHP con soporte para zip usando la opción de configuración--enable-zip.
Los usuarios de Windows deben habilitarphp_zip.dlldentro del ficherophp.inipara poder usar estas funciones.
Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/zip.
Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Existen dos tipos de recursos usados en el módulo Zip. El primero es el directorio Zip para el fichero Zip, el segundo la entrada Zip para la entrada de archivos.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
ZipArchiveusa constantes de clase. Existen tres tipos de constantes: Flags (prefijadas conFL_), errores (prefijados conER_) y modos (sin prefijo).
ZipArchive::CREATE(integer)ZipArchive::OVERWRITE(integer)ZipArchive::EXCL(integer)ZipArchive::RDONLY(integer)ZipArchive::CHECKCONS(integer)ZipArchive::FL_NOCASE(integer)ZipArchive::FL_NODIR(integer)ZipArchive::FL_COMPRESSED(integer)ZipArchive::FL_UNCHANGED(integer)ZipArchive::FL_RECOMPRESS(integer)ZipArchive::FL_ENCRYPTED(integer)ZipArchive::FL_OVERWRITE(integer)ZipArchive::FL_LOCAL(integer)ZipArchive::ZIP_FL_CENTRAL(integer)ZipArchive::FL_ENC_GUESS(integer)ZipArchive::FL_ENC_RAW(integer)ZipArchive::FL_ENC_STRICT(integer)ZipArchive::FL_ENC_UTF_8(integer)ZipArchive::FL_ENC_CP437(integer)ZipArchive::CM_DEFAULT(integer)ZipArchive::CM_STORE(integer)ZipArchive::CM_SHRINK(integer)ZipArchive::CM_REDUCE_1(integer)ZipArchive::CM_REDUCE_2(integer)ZipArchive::CM_REDUCE_3(integer)ZipArchive::CM_REDUCE_4(integer)ZipArchive::CM_IMPLODE(integer)ZipArchive::CM_DEFLATE(integer)ZipArchive::CM_DEFLATE64(integer)ZipArchive::CM_PKWARE_IMPLODE(integer)ZipArchive::CM_BZIP2(integer)ZipArchive::CM_LZMA(integer)ZipArchive::CM_LZMA2(integer)ZipArchive::CM_XZ(integer)ZipArchive::ER_OK(integer)ZipArchive::ER_MULTIDISK(integer)ZipArchive::ER_RENAME(integer)ZipArchive::ER_CLOSE(integer)ZipArchive::ER_SEEK(integer)ZipArchive::ER_READ(integer)ZipArchive::ER_WRITE(integer)ZipArchive::ER_CRC(integer)ZipArchive::ER_ZIPCLOSED(integer)ZipArchive::ER_NOENT(integer)ZipArchive::ER_EXISTS(integer)ZipArchive::ER_OPEN(integer)ZipArchive::ER_TMPOPEN(integer)ZipArchive::ER_ZLIB(integer)ZipArchive::ER_MEMORY(integer)ZipArchive::ER_CHANGED(string)ZipArchive::ER_COMPNOTSUPP(integer)ZipArchive::ER_EOF(integer)ZipArchive::ER_INVAL(integer)ZipArchive::ER_NOZIP(integer)ZipArchive::ER_INTERNAL(integer)ZipArchive::ER_INCONS(integer)ZipArchive::ER_REMOVE(integer)ZipArchive::ER_DELETED(integer)ZipArchive::ER_ENCRNOTSUPP(integer)ZipArchive::ER_RDONLY(integer)ZipArchive::ER_NOPASSWD(integer)ZipArchive::ER_WRONGPASSWD(integer)ZipArchive::ZIP_ER_OPNOTSUPP(integer)ZipArchive::ZIP_ER_INUSE(integer)ZipArchive::ZIP_ER_TELL(integer)ZipArchive::ZIP_ER_COMPRESSED_DATA(integer)ZipArchive::ER_CANCELLED(integer)ZipArchive::EM_NONE(integer)ZipArchive::EM_AES_128(integer)ZipArchive::EM_AES_192(integer)ZipArchive::EM_AES_256(integer)ZipArchive::LIBZIP_VERSION(string)ZipArchive::OPSYS_DOS(integer)ZipArchive::OPSYS_AMIGA(integer)ZipArchive::OPSYS_OPENVMS(integer)ZipArchive::OPSYS_UNIX(integer)ZipArchive::OPSYS_VM_CMS(integer)ZipArchive::OPSYS_ATARI_ST(integer)ZipArchive::OPSYS_OS_2(integer)ZipArchive::OPSYS_MACINTOSH(integer)ZipArchive::OPSYS_Z_SYSTEM(integer)ZipArchive::OPSYS_CPM(integer)ZipArchive::OPSYS_WINDOWS_NTFS(integer)ZipArchive::OPSYS_MVS(integer)ZipArchive::OPSYS_VSE(integer)ZipArchive::OPSYS_ACORN_RISC(integer)ZipArchive::OPSYS_VFAT(integer)ZipArchive::OPSYS_ALTERNATE_MVS(integer)ZipArchive::OPSYS_BEOS(integer)ZipArchive::OPSYS_TANDEM(integer)ZipArchive::OPSYS_OS_400(integer)ZipArchive::OPSYS_OS_X(integer)ZipArchive::OPSYS_DEFAULT(integer)Ejemplo #1 Crear un fichero Zip
<?php
$zip= newZipArchive();
$filename="./test112.zip";
if ($zip->open($filename,ZipArchive::CREATE)!==TRUE) {
exit("cannot open <$filename>\n");
}
$zip->addFromString("testfilephp.txt".time(),"#1 Esto es una cadena de prueba añadida como testfilephp.txt.\n");
$zip->addFromString("testfilephp2.txt".time(),"#2 Esto es una cadena de prueba añadida como testfilephp2.txt.\n");
$zip->addFile($thisdir."/too.php","/testfromfile.php");
echo"numficheros: ".$zip->numFiles."\n";
echo"estado:".$zip->status."\n";
$zip->close();
?>Ejemplo #2 Volcar la información del archivo y listarlos
<?php
$za= newZipArchive();
$za->open('test_with_comment.zip');
print_r($za);
var_dump($za);
echo"numFicheros: ".$za->numFiles."\n";
echo"estado: ".$za->status."\n";
echo"estadosSis: ".$za->statusSys."\n";
echo"nombreFichero: ".$za->filename."\n";
echo"comentario: ".$za->comment."\n";
for ($i=0;$i<$za->numFiles;$i++) {
echo"index:$i\n";
print_r($za->statIndex($i));
}
echo"numFichero:".$za->numFiles."\n";
?>Ejemplo #3 Usando contenedor Zip, leer meta info de OpenOffice
<?php
$reader= newXMLReader();
$reader->open('zip://'.dirname(__FILE__) .'/test.odt#meta.xml');
$odt_meta= array();
while ($reader->read()) {
if ($reader->nodeType==XMLREADER::ELEMENT) {
$elm=$reader->name;
} else {
if ($reader->nodeType==XMLREADER::END_ELEMENT&&$reader->name=='office:meta') {
break;
}
if (!trim($reader->value)) {
continue;
}
$odt_meta[$elm] =$reader->value;
}
}
print_r($odt_meta);
?>Este ejemplo utiliza la antigua API (PHP 4), abre un fichero ZIP, lee cada fichero del archivo y imprime su contenido. El archivotest2.zipusado en este ejmplo es uno de los archivos de prueba la fuente de distribución de ZZIPlib.
Ejemplo #4 Ejemplo del uso de Zip
<?php
$zip=zip_open("/tmp/test2.zip");
if ($zip) {
while ($zip_entry=zip_read($zip)) {
echo"Nombre: ".zip_entry_name($zip_entry) ."\n";
echo"Tamaño actual del fichero: ".zip_entry_filesize($zip_entry) ."\n";
echo"Tamaño comprimido: ".zip_entry_compressedsize($zip_entry) ."\n";
echo"Método de compresión: ".zip_entry_compressionmethod($zip_entry) ."\n";
if (zip_entry_open($zip,$zip_entry,"r")) {
echo"Contenido del fichero:\n";
$buf=zip_entry_read($zip_entry,zip_entry_filesize($zip_entry));
echo"$buf\n";
zip_entry_close($zip_entry);
}
echo"\n";
}
zip_close($zip);
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
Un fichero, comprimido con Zip.
$filepath,$entryname= "",$start= 0,$length= 0,$flags= ZipArchive::FL_OVERWRITEEstado del archivo Zip
Estado del sistema del archivo Zip
Número de ficheros en el archivo
Nombre del archivo en le sistema de archivos
Comentario para el archivo
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)
ZipArchive::addEmptyDir—Añadir un nuevo directorio
$dirname):boolAñade un directoro vacío en el archivo.
dirnameEl directorio a añadir.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Crea un nuevo directorio en un archivo
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
if($zip->addEmptyDir('newDirectory')) {
echo'Creado nuevo directorio root';
} else {
echo'No se puede crear el directorio';
}
$zip->close();
} else {
echo'falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::addFile—Añade un fichero al archivo ZIP para la ruta dada
$filepath,$entryname= "",$start= 0,$length= 0,$flags= ZipArchive::FL_OVERWRITEAñade un fichero al archivo ZIP par la ruta dada.
Nota:Para una portabilidad máxima, se recomienda utilizar siempre barras hacia adelante (
/) como separador de directorios en nombres de ficheros ZIP.
filenameLa ruta del fichero a añadir.
entrynameSi corresponde, este es el nombre local dentro del archivo ZIP que reemplazará elfilepath.
startPara la copia parcial, posición de inicio.
lengthPara la copia parcial, longitud a copiar, si es 0 o -1 se utiliza todo el fichero (empezando porstart).
flagsMáscara de bits compuesta porZipArchive::FL_OVERWRITE,ZipArchive::FL_ENC_GUESS,ZipArchive::FL_ENC_UTF_8,ZipArchive::FL_ENC_CP437. El comportamiento de estas constantes se describe en lapágina de constantes ZIP.
Devuelvetrueen caso de éxito ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 8.0.0 / 1.18.0 | Se añadioflags. |
Este ejemplo abre un archivo ZIPtest.zipy añade el fichero/path/to/index.txt. comonewname.txt.
Ejemplo #1 Abrir y extraer
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
$zip->addFile('/path/to/index.txt','newname.txt');
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>Nota:
Cuando un fichero es añadido al archivo, PHP bloqueará el fichero. El bloqueo se desbloqueará cuando el objetoZipArchivefinalice, ya sea a través deZipArchive::close()o el objetoZipArchivesea destruido. Esto puede impedir que se pueda eliminar el archivo que se está añadiendo hasta después de que el bloqueo haya sido liberado.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::addFromString—Añadir un fichero al archivo ZIP usando su contenido
$localname,string$contents):boolAñade un fichero al archivo ZIP usando su contenido.
localnameNombre de la entrada a crear.
contentsEl contenido a usar para crear la entrada. Es usado en modo binary safe.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Añade una entrada al nuevo fichero
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFromString('test.txt','el contenido del fichero va aquí');
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>Ejemplo #2 Añade un fichero en un directorio dentro de un archivo
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
$zip->addFromString('dir/test.txt','el contenido del fichero va aquí');
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)
ZipArchive::addGlob—Añadir ficheros de un directorio mediante un patrón glob
$pattern,int$flags= 0,array$options= array()):boolAñade ficheros de un directorio que corresponde con el patrón globalpattern.
patternUn patrónglob()contra el cual se hará la correspondencia con los ficheros.
flagsUna máscara de un bit de marcasglob().
optionsUn array asociativo de opciones. Las opciones disponibles son:
"add_path"
Prefijo a indicar cuando se traduce la ruta de acceso del fichero dentro del archivo. Esta traducción se aplica después de cualquier operación de eliminación definida por las opciones"remove_path"o"remove_all_path".
"remove_path"
Prefijo para eliminar la ruta de acceso de los ficheros antes de añadirlos al archivo.
"remove_all_path"
truepara utilizar únicamente el nombre del fichero y añadirlo a la raíz del archivo.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo conZipArchive::addGlob()
Añadir todos los ficheros de scripts y texto php del directorio de trabajo actual
<?php
$zip= newZipArchive();
$ret=$zip->open('application.zip',ZipArchive::OVERWRITE);
if ($ret!==TRUE) {
printf('Erróneo con el código %d',$ret);
} else {
$options= array('add_path'=>'sources/','remove_all_path'=>TRUE);
$zip->addGlob('*.{php,txt}',GLOB_BRACE,$options);
$zip->close();
}
?>(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)
ZipArchive::addPattern—Añade ficheros de un directorio a partir de un patrón PCRE
$pattern,string$path= ".",array$options= array()):arrayAñade ficheros de un directorio que coinciden con la expresión regularpattern. La operación no es recursiva. Únicamente se hará la correspondencia del patrón con el nombre del fichero.
patternUn patrónPCREcontra el cual se realizará la correspondencia.
pathEl directorio que será escaneado. Por defecto es el directorio de trabajo actual.
optionsUn array asociativo de opciones aceptadas porZipArchive::addGlob().
Unarrayde archivos añadidos en caso de éxito ofalseen caso de error
Ejemplo #1 Ejemplo conZipArchive::addPattern()
Añadir todos los scripts y ficheros de texto php del directorio actual
<?php
$zip= newZipArchive();
$ret=$zip->open('application.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE);
if ($ret!==TRUE) {
printf('Erróneo con código %d',$ret);
} else {
$directory=realpath('.');
$options= array('add_path'=>'sources/','remove_path'=>$directory);
$zip->addPattern('/\.(?:php|txt)$/',$directory,$options);
$zip->close();
}
?>(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)
ZipArchive::clearError—Clear the status error message, system and/or zip messages
Clear the status error message, system and/or zip messages.
Esta función no tiene parámetros.
No devuelve ningún valor.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::close—Cierra el fichero activo (abierto o el nuevo creado)
Cierra fichero abierto o creado y guarda los cambios. Este método es automáticamente llamado al finalizar el script.
Esta función no tiene parámetros.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)
ZipArchive::count—Cuenta el número de archivos en el archivo
Esta función no tiene parámetros.
Devuelve el número de ficheros en el archivo.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::deleteIndex—Elimina una entrada en el archivo usando su índice
$index):boolElimina una entrada en su archivo usando su índice.
indexÍndice de la entrada a eliminar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Elimina el fichero desde el archivo usando su índice
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
$zip->deleteIndex(2);
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::deleteName—Elimina una entrada en el archivo por su nombre
$name):boolElimina una entrada en el archivo por su nombre
nameNombre de la entrada a eliminar.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Eliminado un fichero y un directorio desde un archivo, usando nombres
<?php
$zip= newZipArchive;
if ($zip->open('test1.zip') ===TRUE) {
$zip->deleteName('testfromfile.php');
$zip->deleteName('testDir/');
$zip->close();
echo'ok';
} else {
echo'Falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::extractTo—Extraer el contenido del archivo
Extrae el archivo completo o los ficheros dados en la ruta que se especifique.
Los permisos por omisión para los archivos y directorios extraídos dan el más amplio acceso posible. Esto se puede restringir estableciendo la umask actual, que se puede cambiar usandoumask().
destinationDestino en donde extraer los ficheros.
entriesLas entradas a extraer. Acepta tanto un solo nombre o un array de nombres.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Extraer todas las entradas
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
$zip->extractTo('/my/destination/dir/');
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>Ejemplo #2 Extraer dos entradas
<?php
$zip= newZipArchive;
$res=$zip->open('test_im.zip');
if ($res===TRUE) {
$zip->extractTo('/my/destination/dir/', array('pear_item.gif','testfromfile.php'));
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::getArchiveComment—Devuelve el comentario del archivo ZIP
$flags= ?):stringDevuelve el comentario del archivo ZIP.
flagsSi las flags se establecen enZipArchive::FL_UNCHANGED, el comentario original se devuelve sin cambios.
Devuelve el comentario del archivo Zip ofalseen caso de error.
Ejemplo #1 Vuelca el comentario del archivo
<?php
$zip= newZipArchive;
$res=$zip->open('test_with_comment.zip');
if ($res===TRUE) {
var_dump($zip->getArchiveComment());
/* O usando la propiedad del archivo */
var_dump($zip->comment);
} else {
echo'falló, código:'.$res;
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)
ZipArchive::getCommentIndex—Devuelve el comentario de una entrada usando la entrada díndice
$index,int$flags= ?):stringDevuelve el comentario de una entrada usando la entrada índice.
indexÍndice de la entrada
flagsSi flagsZipArchive::FL_UNCHANGED, se devolverá el comentario original no cambiado.
Con éxito devuelve el comentario ofalseen caso de error.
Ejemplo #1 Vuelca el comentario de la entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test1.zip');
if ($res===TRUE) {
var_dump($zip->getCommentIndex(1));
} else {
echo'falló, código:'.$res;
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)
ZipArchive::getCommentName—Devuelve el comentario de una entrada usando el nombre de la entrada
$name,int$flags= ?):stringDevuelve el comentario de una entrada usando el nombre de la entrada.
nameNombre de la entrada
flagsSi flags está defindo aZipArchive::FL_UNCHANGED, se devuelve el comentario original no cambiado.
Devuelve el comentario si se ejecutó con éxito ofalseen caso de error.
Ejemplo #1 Vuelca el comentario de la entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test1.zip');
if ($res===TRUE) {
var_dump($zip->getCommentName('test/entry1.txt'));
} else {
echo'Falló, código:'.$res;
}
?>(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)
ZipArchive::getExternalAttributesIndex—Obtener los atributos externos de una entrada definida por su índice
$index,&$opsys,&$attr,$flags= ?Recuperar los atributos externos de una entrada definida por su índice.
indexEl índice de la entrada.
opsysEn caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
attrEn caso de éxito, recibe los atributos externos. El valor dependerá del sistema operativo.
flagsSi flags se establece aZipArchive::FL_UNCHANGED, se devuelven los atributos originales sin cambios.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo extrae todas las entradas de un archivo ZIPtest.zipy asigna los permisos Unix tomados de los atributos externos.
Ejemplo #1 Extraer todas las entradas con permisos Unix
<?php
$zip= newZipArchive();
if ($zip->open('test.zip') ===TRUE) {
for ($idx=0;$s=$zip->statIndex($idx) ;$idx++) {
if ($zip->extractTo('.',$s['name'])) {
if ($zip->getExternalAttributesIndex($idx,$opsys,$attr)
&&$opsys==ZipArchive::OPSYS_UNIX) {
chmod($s['name'], ($attr>>16) &0777);
}
}
}
$zip->close();
echo"Ok\n";
} else {
echo"KO\n";
}
?>(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)
ZipArchive::getExternalAttributesName—Obtener los atributos externos de una entrada definida por su nombre
$name,&$opsys,&$attr,$flags= ?Obtener los atributos externos de una entrada definida por su nombre.
nameEl nombre de la entrada.
opsysEn caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
attrEn caso de éxito, recibe los atributos externos. El valor depende del sistema operativo.
flagsSi flags se establece aZipArchive::FL_UNCHANGED, se devuelven los atributos originales sin cambios.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::getFromIndex—Devuelve el contenido de la entrada usando su índice
$index,int$length= 0,int$flags= ?):stringDevuelve el contenido de la entrada usando su índice.
indexEl índice de la entrada
lengthLa longitud que se see desde la entrada. Si es0, entonces toda la entrada se lee.
flagsLas flags usadas para abrir el fichero. Los siguientes valores pueden ser Ored.
ZipArchive::FL_UNCHANGED
ZipArchive::FL_COMPRESSED
Devuelve el contenido de la entrada si se ejecutó con éxito ofalseen caso de error.
Ejemplo #1 Obtener el contenido del fichero
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
echo$zip->getFromIndex(2);
$zip->close();
} else {
echo'falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::getFromName—Devuelve el contenido de la entrada utilizando su nombre
$name,int$length= 0,int$flags= ?):stringDevuelve el contenido de la entrada utilizando su nombre
nameNombre de la entrada
lengthLa longitud a ser leída desde la entrada. Si es0, entonces toda la entrada es leída.
flagsLos indicadores a utilizar para abrir el archivo. Los siguientes valores podrían ser escritos juntos con un OR lógico en él.
ZipArchive::FL_UNCHANGED
ZipArchive::FL_COMPRESSED
ZipArchive::FL_NOCASE
Devuelve el contenido de la entrada en caso de tener éxito, ofalseen caso de error.
Ejemplo #1 Obtener el contenido de los ficheros
<?php
$zip= newZipArchive;
if ($zip->open('test1.zip') ===TRUE) {
echo$zip->getFromName('testfromfile.php');
$zip->close();
} else {
echo'falló';
}
?>Ejemplo #2 Convierte una imagen desde una entrada de fichero zip
<?php
$z= newZipArchive();
if ($z->open(dirname(__FILE__) .'/test_im.zip')) {
$im_string=$z->getFromName("pear_item.gif");
$im=imagecreatefromstring($im_string);
imagepng($im,'b.png');
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::getNameIndex—Devuelve el nombre de una entrada utilizando su índice
$index,int$flags= ?):stringDevuelve el nombre de una entrada utilizando su índice.
indexEl índice de la entrada.
flagsSi las flags se establecen enZipArchive::FL_UNCHANGED, el nombre original es devuelto sin cambios.
Devuelve el nombre en caso de tener éxito, ofalseen caso de error.
Ejemplo #1 Ejemplo deZipArchive::getNameIndex()
<?php
if ($zip->open('test.zip') ==TRUE) {
for ($i=0;$i<$zip->numFiles;$i++) {
$filename=$zip->getNameIndex($i);
// ...
}
}
?>(PHP 5 >= 5.2.7, PHP 7, PHP 8)
ZipArchive::getStatusString—Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip
Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip.
Esta función no tiene parámetros.
Devuelve unstringcon el mensaje de estado en caso de tener éxito, ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 8.0.0 / 1.18.0 | Este método puede ser llamado en un archivo cerrado. |
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::getStream—Obtener un manejador de fichero para la entrada definido por su nombre (sólo lectura)
$name):resourceObtener un manejador de fichero para la entrada definido por su nombre. Por ahora, éste solamente soporta operaciones de lectura.
nameEl nombre de la entrada a utilizar.
Devuelve un puntero de fichero (un recurso) en caso de tener éxito, ofalseen caso de error.
Ejemplo #1 Obtiene los contenidos de entrada confread()y lo almacena
<?php
$contents='';
$z= newZipArchive();
if ($z->open('test.zip')) {
$fp=$z->getStream('test');
if(!$fp) exit("failed\n");
while (!feof($fp)) {
$contents.=fread($fp,2);
}
fclose($fp);
file_put_contents('t',$contents);
echo"done.\n";
}
?>Ejemplo #2 Lo mismo como el ejemplo anterior pero confopen()y el envoltorio de flujo de zip
<?php
$contents='';
$fp=fopen('zip://'.dirname(__FILE__) .'/test.zip#test','r');
if (!$fp) {
exit("cannot open\n");
}
while (!feof($fp)) {
$contents.=fread($fp,2);
}
echo"$contents\n";
fclose($fp);
echo"done.\n";
?>Ejemplo #3 El flujo de envoltorio y la imagen, también pueden ser utilizados con la función xml
<?php
$im=imagecreatefromgif('zip://'.dirname(__FILE__) .'/test_im.zip#pear_item.gif');
imagepng($im,'a.png');
?>(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)
ZipArchive::getStreamIndex—Get a file handler to the entry defined by its index (read only)
$index,int$flags= 0):resource|falseGet a file handler to the entry defined by its index. For now, it only supports read operations.
indexIndex of the entry
flagsIf flags is set toZipArchive::FL_UNCHANGED, the original unchanged stream is returned.
Returns a file pointer (resource) on success ofalseen caso de error.
Ejemplo #1 Get the entry contents withfread()and store it
<?php
$contents='';
$z= newZipArchive();
if ($z->open('test.zip')) {
$fp=$z->getStreamIndex(1,ZipArchive::FL_UNCHANGED);
if(!$fp) die($z->getStatusString());
echostream_get_contents($fp);
fclose($fp);
}
?>(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)
ZipArchive::getStreamName—Get a file handler to the entry defined by its name (read only)
$name,int$flags= 0):resource|falseGet a file handler to the entry defined by its name. For now, it only supports read operations.
nameThe name of the entry to use.
flagsIf flags is set toZipArchive::FL_UNCHANGED, the original unchanged stream is returned.
Returns a file pointer (resource) on success ofalseen caso de error.
Ejemplo #1 Get the entry contents withfread()and store it
<?php
$contents='';
$z= newZipArchive();
if ($z->open('test.zip')) {
$fp=$z->getStreamName('test',ZipArchive::FL_UNCHANGED);
if(!$fp) die($z->getStatusString());
echostream_get_contents($fp);
fclose($fp);
}
?>(PHP >= 8.0.0, PECL zip >= 1.19.0)
ZipArchive::isCompressionMethodSupported—Check if a compression method is supported by libzip
$method,bool$enc=true):boolCheck if a compression method is supported by libzip.
methodThe compression method, one of theZipArchive::CM_*constants.
encIftruecheck for compression, else check for decompression.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
This function is only available if built against libzip ≥ 1.7.0.
(PHP >= 8.0.0, PECL zip >= 1.19.0)
ZipArchive::isEncryptionMethodSupported—Check if a encryption method is supported by libzip
$method,bool$enc=true):boolCheck if a compression method is supported by libzip.
methodThe encryption method, one of theZipArchive::EM_*constants.
encIftruecheck for encryption, else check for decryption.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
This function is only available if built against libzip ≥ 1.7.0.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::locateName—Devuelve el índice de la entrada en el archivo
$name,int$flags= ?):intLocaliza una entrada utilizando su nombre.
nameEl nombre de la entrada a buscar
flagsLos indicadores son especificados agregándoles OR a los siguientes valores, ó 0 para ninguno de ellos.
ZipArchive::FL_NOCASE
ZipArchive::FL_NODIR
Devuelve el índice de la entrada en caso de tener éxito, ofalseen caso de error.
Ejemplo #1 Crear un archivo y luego utilizarlo conZipArchive::locateName()
<?php
$file='testlocate.zip';
$zip= newZipArchive;
if ($zip->open($file,ZipArchive::CREATE) !==TRUE) {
exit('falló');
}
$zip->addFromString('entry1.txt','entry #1');
$zip->addFromString('entry2.txt','entry #2');
$zip->addFromString('dir/entry2d.txt','entry #2');
if (!$zip->status==ZipArchive::ER_OK) {
echo"falló al escribir en el archivo zip\n";
}
$zip->close();
if ($zip->open($file) !==TRUE) {
exit('falló');
}
echo$zip->locateName('entry1.txt') ."\n";
echo$zip->locateName('eNtry2.txt') ."\n";
echo$zip->locateName('eNtry2.txt',ZipArchive::FL_NOCASE) ."\n";
echo$zip->locateName('enTRy2d.txt',ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) ."\n";
$zip->close();
?>El resultado del ejemplo sería:
El ejemplo de arriba mostrará la salida: 0 1 2
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::open—Abrir un fichero de archivo en formato ZIP
Abre un archivo zip nuevo o existente para leer, escribir o modificar.
Desde libzip 1.6.0, un archivo vacío ya no es un archivo válido.
filenameEl nombre del fichero del archivo ZIP para ser abierto.
flagsEl modo a utilizar para abrir el archivo.
Error codesDevuelvetrueen caso de éxito o el código de error.
ZipArchive::ER_EXISTS
El fichero ya existe.
ZipArchive::ER_INCONS
Archivo zip inconsistente.
ZipArchive::ER_INVAL
Argumento no válido.
ZipArchive::ER_MEMORY
Falló malloc.
ZipArchive::ER_NOENT
No existe el fichero.
ZipArchive::ER_NOZIP
No es un archivo zip.
ZipArchive::ER_OPEN
No se puede abrir el fichero.
ZipArchive::ER_READ
Error de lectura.
ZipArchive::ER_SEEK
Error de búsqueda.
Ejemplo #1 Abrir y extraer
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
echo'ok';
$zip->extractTo('test');
$zip->close();
} else {
echo'falló, código:'.$res;
}
?>Ejemplo #2 Crear un fichero
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFromString('test.txt','el contenido del fichero va aquí');
$zip->addFile('data.txt','entryname.txt');
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>Ejemplo #3 Crear un fichero temporal
<?php
$name=tempnam(sys_get_temp_dir(),"FOO");
$zip= newZipArchive;
$res=$zip->open($name,ZipArchive::OVERWRITE);/* truncate as empty file is not valid */
if ($res===TRUE) {
$zip->addFile('data.txt','entryname.txt');
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>(PHP >= 8.0.0, PECL zip >= 1.17.0)
ZipArchive::registerCancelCallback—Registrar una llamada para permitir la cancelación durante el cierre del archivo
Registrar una funcióncallbackpara permitir la cancelación durante el cierre del archivo.
callbackSi esta función vuelve a 0, la operación continuará, otro valor será cancelado.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.6.0.
Este ejemplo crea un archivo ZIPphp.zipy cancela la operación en alguna condición de operación.
Ejemplo #1 Archive a file
<?php
$zip= newZipArchive();
if ($zip->open('php.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY,'php');
$zip->registerCancelCallback(function () {
return ($someruncondition? -1:0);
});
$zip->close();
}(PHP >= 8.0.0, PECL zip >= 1.17.0)
ZipArchive::registerProgressCallback—Registra una llamada para proporcionar actualizaciones durante el cierre del archivo
Registra una funcióncallbackpara proporcionar actualizaciones durante el cierre del archivo.
rateCambiar entre cada llamada de la devolución de llamada (de 0.0 a 1.0).
callbackEsta función recibirá el actualstatecomo unfloat(de 0.0 a 1.0).
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.3.0.
Este ejemplo crea un archivo ZIPphp.zipy muestra la progresión.
Ejemplo #1 Archive a file
$zip = new ZipArchive();
if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY, 'php');
$zip->registerProgressCallback(0.05, function ($r) {
printf("%d%%\n", $r * 100);
});
$zip->close();
}(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::renameIndex—Renombra una entrada definida por su índice
$index,string$newname):boolRenombra una entrada definida por su índice.
indexÍndice de la entrada a renombrar.
newnameNombre nuevo.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Renombra una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
$zip->renameIndex(2,'newname.txt');
$zip->close();
} else {
echo'falló, código:'.$res;
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::renameName—Renombra una entrada definida por su nombre
$name,string$newname):boolRenombra una entrada definida por su nombre.
nameNombre de la entrada a renombrar.
newnameNombre nuevo.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Renombra una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
$zip->renameName('currentname.txt','newname.txt');
$zip->close();
} else {
echo'falló, código:'.$res;
}
?>(PHP >= 8.0.0, PECL zip >= 1.18.0)
ZipArchive::replaceFile—Reemplaza fichero en el archivo ZIP con una ruta determinada
$filename,$index,$start= 0,$length= 0,$flags= 0Reemplaza fichero en el archivo ZIP con una ruta determinada.
Nota:Para una portabilidad máxima, se recomienda utilizar siempre barras hacia adelante (
/) como separador de directorios en nombres de ficheros ZIP.
filenameLa ruta del archivo a añadir.
indexEl índice del archivo a reemplazar, su nombre no ha cambiado.
startPara la copia parcial, posición de inicio.
lengthPara la copia parcial, la longitud a copiar, si 0 o -1 el archivo completo es usado (a partir destart).
flagsLa máscara de bits consiste enZipArchive::FL_ENC_GUESS,ZipArchive::FL_ENC_UTF_8,ZipArchive::FL_ENC_CP437. El comportamiento de estas constantes se describe en la páginaconstantes ZIP.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo abre un archivo ZIPtest.zipy sustituye la entrada del índice 1 con/path/to/index.txt.
Ejemplo #1 Abrir y reemplazar
<?php
$zip= newZipArchive;
if ($zip->open('test.zip') ===TRUE) {
$zip->replaceFile('/path/to/index.txt',1);
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)
ZipArchive::setArchiveComment—Establece el comentario de un archivo ZIP
$comment):boolEstablece el comentario de un archivo ZIP.
commentLos contenidos del comentario.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Crear un archivo y establecer un comentario
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFromString('test.txt','El contenido del fichero va aquí');
$zip->setArchiveComment('nuevo comentario del archivo');
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)
ZipArchive::setCommentIndex—Establece el comentario de una entrada definido por su índice
$index,string$comment):boolEstablece el comentario de una entrada definido por su índice.
indexÍndice de la entrada.
commentLos contenidos del comentario.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
$zip->setCommentIndex(2,'comentario de la entrada nueva');
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)
ZipArchive::setCommentName—Establece el comentario de una entrada definido por su nombre
$name,string$comment):boolEstablece el comentario de una entrada definido por su nombre.
nameNombre de la entrada.
commentLos contenidos del comentario.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
$zip->setCommentName('entry1.txt','comentario de la entrada nueva');
$zip->close();
echo'ok';
} else {
echo'falló';
}
?>(PHP 7, PHP 8, PECL zip >= 1.13.0)
ZipArchive::setCompressionIndex—Establecer el método de compresión de una entrada definida por su índice
$index,int$comp_method,int$comp_flags= 0):boolEstablecer el método de compresión de una entrada definida por su índice.
indexEl índice de la entrada.
comp_methodEl método de compresión, una de las constantesZipArchive::CM_*.
comp_flagsNivel de compresión.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFromString('foo','Un texto');
$zip->addFromString('bar','Otro texto');
$zip->setCompressionIndex(0,ZipArchive::CM_STORE);
$zip->setCompressionIndex(1,ZipArchive::CM_DEFLATE);
$zip->close();
echo'ok';
} else {
echo'fallo';
}
?>(PHP 7, PHP 8, PECL zip >= 1.13.0)
ZipArchive::setCompressionName—Establecer el método de compresión de una entrada definida por su nombre
$name,int$comp_method,int$comp_flags= 0):boolEstablecer el método de compresión de una entrada definida por su nombre.
nameEl nombre de la entrada.
comp_methodEl método de compresión. Una de las constantesZipArchive::CM_*.
comp_flagsNivel de compresión.
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFromString('foo','Un texto');
$zip->addFromString('bar','Otro texto');
$zip->setCompressionName('foo',ZipArchive::CM_STORE);
$zip->setCompressionName('bar',ZipArchive::CM_DEFLATE);
$zip->close();
echo'ok';
} else {
echo'fallo';
}
?>Ejemplo #2 Añadir fichero y establecer el método de compresión
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if ($res===TRUE) {
$zip->addFile('foo.jpg','bar.jpg');
$zip->setCompressionName('bar.jpg',ZipArchive::CM_XZ);
$zip->close();
echo'ok';
} else {
echo'failed';
}
?>(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)
ZipArchive::setEncryptionIndex—Establece el método de cifrado de una entrada definida por su índice
$index,string$method,string$password= ?):boolEstablece el método de cifrado de una entrada definida por su índice.
indexÍndice de la entrada.
methodEl método de cifrado definido por una de las constantes ZipArchive::EM_ constants.
passwordContraseña opcional, se utiliza por defecto cuando falta.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.
(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)
ZipArchive::setEncryptionName—Establece el método de cifrado de una entrada definida por su nombre
$name,int$method,string$password= ?):boolEstablece el método de cifrado de una entrada definida por su nombre.
nameNombre de la entrada.
methodEl método de encriptación definido por una de las constantes ZipArchive::EM_constants.
passwordContraseña opcional, se utiliza por defecto cuando falta.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtencriptado usando el método AES 256.
Ejemplo #1 Archivar y encriptar un archivo
<?php
$zip= newZipArchive();
if ($zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->setPassword('secret');
$zip->addFile('text.txt');
$zip->setEncryptionName('text.txt',ZipArchive::EM_AES_256);
$zip->close();
echo"Ok\n";
} else {
echo"KO\n";
}
?>Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.
(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)
ZipArchive::setExternalAttributesIndex—Establece los atributos externos de una entrada definida por su índice
$index,$opsys,$attr,$flags= ?Establece los atributos externos de una entrada definida por su índice.
indexEl índice de la entrada.
opsysEl código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
attrLos atributos externos. El valor depende del sistema operativo.
flagsBanderas opcionales. Actualmente no se utiliza.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)
ZipArchive::setExternalAttributesName—Establece los atributos externos de una entrada definida por su nombre
$name,$opsys,$attr,$flags= ?Establece los atributos externos de una entrada definida por su nombre.
nameEl nombre de la entrada.
opsysEl código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.
attrLos atributos externos. El valor depende del sistema operativo.
flagsBanderas opcionales. Actualmente no se utiliza.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo abre un archivo comprimido ZIPtest.zipy añade el ficherotest.txtcon sus permisos Unix como atributos externos.
Ejemplo #1 Archivar un fichero, con sus permisos Unix
<?php
$zip= newZipArchive();
$stat=stat($filename='test.txt');
if (is_array($stat) &&$zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile($filename);
$zip->setExternalAttributesName($filename,ZipArchive::OPSYS_UNIX,$stat['mode'] <<16);
$zip->close();
echo"Ok\n";
} else {
echo"KO\n";
}
?>(PHP >= 8.0.0, PECL zip >= 1.16.0)
ZipArchive::setMtimeIndex—Establece el tiempo de modificación de una entrada definido por su índice
$index,int$timestamp,int$flags= ?):boolEstablece el tiempo de modificación de una entrada definido por su índice.
indexÍndice de la entrada.
timestampLa hora de modificación (unix timestamp) del archivo.
flagsFlags opcionales, sin usar por ahora.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtcon su fecha de modificación.
Ejemplo #1 Archivar un fichero
<?php
$zip= newZipArchive();
if ($zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile('text.txt');
$zip->setMtimIndex(0,mktime(0,0,0,12,25,2019));
$zip->close();
echo"Ok\n";
} else {
echo"KO\n";
}
?>Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.
(PHP >= 8.0.0, PECL zip >= 1.16.0)
ZipArchive::setMtimeName—Establece la hora de modificación de una entrada definida por su nombre
$name,int$timestamp,int$flags= ?):boolEstablece la hora de modificación de una entrada definida por su nombre.
nameNombre de la entrada.
timestampLa hora de modificación (unix timestamp) del archivo.
flagsFlags opcionales, sin usar por ahora.
Devuelvetrueen caso de éxito ofalseen caso de error.
Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtcon su fecha de modificación.
Ejemplo #1 Archivar un fichero
<?php
$zip= newZipArchive();
if ($zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile('text.txt');
$zip->setMtimeName('text.txt',mktime(0,0,0,12,25,2019));
$zip->close();
echo"Ok\n";
} else {
echo"KO\n";
}
?>Nota:
Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.
(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)
ZipArchive::setPassword—Establece la contraseña para el archivo activo
$password):boolEstablece la contraseña para el archivo activo.
passwordLa contraseña a emplear para el archivo.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
A partir de PHP 7.2.0 y libzip 1.2.0 la contraseña se utiliza para descomprimir el archivo, y también es la contraseña por omisión paraZipArchive::setEncryptionName()yZipArchive::setEncryptionIndex(). Anteriormente, esta función sólo establecía la contraseña que se usaría para descomprimir el archivo; No se convirtió en un no protegido con contraseñaZipArchiveen un protegido con contraseñaZipArchive.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::statIndex—Obtiene los detalles de una entrada definida por su índice
$index,int$flags= ?):arrayLa función obtiene información acerca de la entrada definida por su índice.
indexÍndice de la entrada
flagsZipArchive::FL_UNCHANGEDpodría ser puesto con otros OR lógicos en él para pedir información acerca del fichero original en el archivo, ignorando cualquiera de los cambios hechos.
Devuelve una matríz conteniendo los detalles de la entrada, ofalseen caso de error.
Ejemplo #1 Volcar la información estadística de una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
print_r($zip->statIndex(3));
$zip->close();
} else {
echo'falló, código:'.$res;
}
?>El resultado del ejemplo sería algo similar a:
Array
(
[name] => foobar/baz
[index] => 3
[crc] => 499465816
[size] => 27
[mtime] => 1123164748
[comp_size] => 24
[comp_method] => 8
)
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::statName—Obtener los detalles de una entrada definida por su nombre
$name,int$flags= ?):arrayLa función obtiene información acerca de la entrada definida por su nombre.
nameNombre de la entrada
flagsEl argumento flags especifica cómo la búsqueda del nombre debería se hecho. También,ZipArchive::FL_UNCHANGEDpodría ser puesta con otros OR en él para solicitar la información acerca del fichero original en el archivo, ignorando cualquier cambio realizado.
ZipArchive::FL_NOCASE
ZipArchive::FL_NODIR
ZipArchive::FL_UNCHANGED
Devuelve una matríz que contenie detalles de la entrada ofalseen caso de error.
Ejemplo #1 Volcar la información estadística de una entrada
<?php
$zip= newZipArchive;
$res=$zip->open('test.zip');
if ($res===TRUE) {
print_r($zip->statName('foobar/baz'));
$zip->close();
} else {
echo'falló, código:'.$res;
}
?>El resultado del ejemplo sería algo similar a:
Array
(
[name] => foobar/baz
[index] => 3
[crc] => 499465816
[size] => 27
[mtime] => 1123164748
[comp_size] => 24
[comp_method] => 8
)
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::unchangeAll—Deshacer todos los cambios hechos en el archivo
Deshacer todos los cambios hechos en el archivo.
Esta función no tiene parámetros.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::unchangeArchive—Revertir todos los cambios globales hechos en el archivo
Revertir todos los cambios globales en el archivo. Por ahora, esto solamente revierte los cambios de los comentarios del archivo.
Esta función no tiene parámetros.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)
ZipArchive::unchangeIndex—Revertir todos los cambios hechos a una entrada en el índice dado
$index):boolRevertir todos los cambios hechos a una entrada en el índice dado.
indexÍndice de la entrada.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)
ZipArchive::unchangeName—Deshace todos los cambios realizados a una entrada con un nombre dado
$name):boolDeshacer todos los cambios hechos a una entrada.
nameNombre de la entrada.
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_close—Cierra un fichero ZIP
$zip):voidCierra el archivo ZIP archivo dado.
zipUn fichero ZIP previamente abierto conzip_open().
No devuelve ningún valor.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_close—Cierra la entrada a un directorio
$zip_entry):boolCierra la entrada del directorio especificado.
zip_entryUna entrada del directorio previamente abierto conzip_entry_open().
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_compressedsize—Obtiene el tamaño comprimido de una entrada de directorio
$zip_entry):intDevuelve el tamaño comprimido de una especifica entrada de directorio.
zip_entryUna entrada de directorio devuelva porzip_read().
El tamaño comprimido.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_compressionmethod—Devuelve el método de compresión de una entrada de directorio
$zip_entry):stringDevuelve el método de compresión de una entrada de directorio especificada porzip_entry.
zip_entryUna entrada de directorio devuelta porzip_read().
El método de compresión.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_filesize—Devuelve el tamaño del fichero actual de una entrada de directorio
$zip_entry):intDevuelve el tamaño actual de una entrada de directorio específica.
zip_entryUna entrada de directorio devuelva porzip_read().
El tamaño de una entrada de directorio.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_name—Devuelve el nombre de la entrada de un directorio
$zip_entry):stringDevuelve el nombre de una entrada de directorio específica.
zip_entryUna entrada de directorio devuelta porzip_read().
El nombre de la entrada de directorio.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_open—Abrir una entrada de directorio para lectura
$zip,resource$zip_entry,string$mode= ?):boolAbre una entrada de directorio en un fichero zip para lectura.
zipUn válido controlador de recurso es devuelto porzip_open().
zip_entryUna entrada de directorio es devuelta porzip_read().
modeCualquiera de los modos especificados en la documentación defopen().
Nota:
Actualmente, el
modees ignorado y es siempre"rb". Esto es debido al hecho que el soporte zip en PHP es solamente de acceso lectura.
Devuelvetrueen caso de éxito ofalseen caso de error.
Nota:
A diferencia defopen()y otras funciones similares, el valor devuelto porzip_entry_open()solo indica el resultado de la operación y no es necesario para la lectura o cerrado de la entrada de directorio.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_entry_read—Leer desde una entrada de directorio abierta
$zip_entry,int$length= 1024):stringLee desde una entrada de directorio abierta.
zip_entryUn directorio devuelto porzip_read().
lengthEl número de bytes a devolver.
Nota:
Esto debería ser el tramo descomprimido que se desea leer.
Devuelve los datos leídos, un string vacío si se encuentra al final de un fichero, ofalseen case de error.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_open—Abre un fichero ZIP
$filename):resourceAbre un nuevo fichero ZIP para su lectura.
filenameEl nombre del fichero ZIP a abrir.
Devuelve un manejador del recurso para usarlo después conzip_read()yzip_close()o devolver el número de error sifilenameno existe o en caso de otro error.
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)
zip_read—Leer la siguiente entrada en el fichero ZIP
$zip):resourceLee la siguiente entrada en un fichero zip.
zipUn fichero ZIP previamente abierto conzip_open().
Devuelve un recurso de una entrada de directorio para poder usar luego las funcioneszip_entry_..., ofalsesi no hay más entradas a leer, o código de error en caso de ocurrir otro error.
Este módulo permite leer y escribir ficheros comprimidos con gzip (.gz) de forma transparente, a través de las versiones de la mayoría de las funciones desistemas de ficherosque trabajan con ficheros comprimidos con gzip (y también con ficheros descomprimidos, pero no con sockets).
Nota:
La versión 4.0.4 introdujo una envoltura basada en fopen para ficheros.gz, así que se puede usar la URL especialzlib:para acceder de forma trasparente a los ficheros comprimidos usando las funciones normales f*() de acceso a ficheros si se prefija el nombre de fichero o la ruta conzlib:cuando se llama afopen(). Esta característica requiere una biblioteca en tiempo de ejecución en C que provea la función
fopencookie(). Hasta ahora, GNU libc parece ser la única biblioteca que ofrece esta característica.En PHP 4.3.0,zlib:ha sido cambiado acompress.zlib://para evitar ambigüedades con los nombres de fichero que contengan caracteres '
:'. La funciónfopencookie()ya no es necesaria. Hay más información disponible en la sección sobrezlib://.
Este módulo usa las funciones de» zlibpor Jean-loup Gailly y Mark Adler. Se tiene que utilizar la versión >= 1.0.9 de zlib con éste módulo. Desde PHP 5.4.0 se tiene que usar zlib >= 1.2.0.4.
El soporte para Zlib en PHP no está activado por defecto. Es necesario configurar PHP con la opción--with-zlib[=DIR]
La versión de PHP para Windows tiene soporte nativo para esta extensión. No se requiere cargar extensiones adicionales para utilizar estas funciones.
El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.
La extensión zlib ofrece la opción de comprimir de manera trasparente las páginas sobre la marcha, si el navegador que hace la solicitud lo soporta. Por lo tanto hay tres opciones en elarchivo de configuraciónphp.ini.
| Nombre | Por defecto | Cambiable | Historial de cambios |
|---|---|---|---|
| zlib.output_compression | "0" | PHP_INI_ALL | |
| zlib.output_compression_level | "-1" | PHP_INI_ALL | |
| zlib.output_handler | "" | PHP_INI_ALL |
He aquí una breve explicación de las directivas de configuración.
zlib.output_compressionbool/intPara comprimir páginas transparentemente. Si esta opción está configurada en "On" enphp.inio en la configuración de Apache, las páginas serán comprimidas si el navegador envía un encabezado "Accept-Encoding: gzip" o "deflate". Los encabezados "Content-Encoding: gzip" (respectivamente "deflate") y "Vary: Accept-Encoding" serán agregados a la salida. En tiempo de ejecución, esto se puede configurar sólo antes de enviar cualquier salida.
Esta opción también acepta valores enteros (integer) en lugar de boolean en "On"/"Off", usando esto se puede configurar el tamaño del buffer de salida (por defecto es 4KB).
Nota:
output_handlerdebe estar vacío si ésta se configura en 'On' ! De otra manera se debe usar
zlib.output_handler.
zlib.output_compression_levelintNivel de compresión usado para la salida de la compresión transparente. Especifica un valor entre 0 (no comprimido) y 9 (máxima compresión). El valor por defecto es -1, que deja que el servidor decida cual nivel utilizar.
zlib.output_handlerstringNo se pueden especificar manejadores adicionales de salida si zlib.output_compression está activada aquí. Esta configuración hace lo mismo queoutput_handlerpero en un orden diferente.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
FORCE_GZIP(integer)FORCE_DEFLATE(integer)ZLIB_ENCODING_RAW(integer)ZLIB_ENCODING_DEFLATE(integer)ZLIB_ENCODING_GZIP(integer)ZLIB_FILTERED(integer)ZLIB_HUFFMAN_ONLY(integer)ZLIB_FIXED(integer)ZLIB_RLE(integer)ZLIB_DEFAULT_STRATEGY(integer)ZLIB_BLOCK(integer)ZLIB_NO_FLUSH(integer)ZLIB_PARTIAL_FLUSH(integer)ZLIB_SYNC_FLUSH(integer)ZLIB_FULL_FLUSH(integer)ZLIB_FINISH(integer)Este ejemplo abre un archivo temporal y escribe una cadena de prueba en él, entonces muestra el contenido de este archivo dos veces.
Ejemplo #1 Pequeño Ejemplo de Zlib
<?php
$filename=tempnam('/tmp','zlibtest') .'.gz';
echo"<html>\n<head></head>\n<body>\n<pre>\n";
$s="Sólo una prueba, prueba, prueba, prueba, prueba, prueba!\n";
// abre el archivo para escribir con compresión máxima
$zp=gzopen($filename,"w9");
// escribe la cadena en el archivo
gzwrite($zp,$s);
// cierra el archivo
gzclose($zp);
// abre el archivo para lectura
$zp=gzopen($filename,"r");
// lee el tercer carácter
echogzread($zp,3);
// salida hasta el fin del archivo y lo cierra
gzpassthru($zp);
gzclose($zp);
echo"\n";
// abre el archivo y muestra el contenido (por segunda vez).
if (readgzfile($filename) !=strlen($s)) {
echo"Error con funciones de zlib!";
}
unlink($filename);
echo"</pre>\n</body>\n</html>\n";
?>Ejemplo #2 Trabajando con la API de compresión y descompresión increemental desde PHP 7.0.0
// Perform GZIP compression:
$deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
$compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);?>
// Perform GZIP decompression:
$inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
$uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
$uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
echo $uncompressed;El resultado del ejemplo sería:
Data to compress, more data, and even more data!
(PHP 7, PHP 8)
deflate_add—Incrementally deflate data
Incrementally deflates data in the specified context.
contextA context created withdeflate_init().
dataA chunk of data to compress.
flush_modeOne ofZLIB_BLOCK,ZLIB_NO_FLUSH,ZLIB_PARTIAL_FLUSH,ZLIB_SYNC_FLUSH(default),ZLIB_FULL_FLUSH,ZLIB_FINISH. Normally you will want to setZLIB_NO_FLUSHto maximize compression, andZLIB_FINISHto terminate with the last chunk of data. See the» zlib manualfor a detailed description of these constants.
Returns a chunk of compressed data, ofalseen caso de error.
If invalid arguments are given, an error of levelE_WARNINGis generated.
| Versión | Descripción |
|---|---|
| 8.0.0 | contextexpects aDeflateContextinstance now; previously, aresourcewas expected. |
(PHP 7, PHP 8)
deflate_init—Initialize an incremental deflate context
Initializes an incremental deflate context using the specifiedencoding.
Note that thewindowoption here only sets the window size of the algorithm, differently from the zlib filters where the same parameter also sets the encoding to use; the encoding must be set with theencodingparameter.
Limitation: there is currently no way to set the header information on a GZIP compressed stream, which are set as follows: GZIP signature (\x1f\x8B); compression method (\x08== DEFLATE); 6 zero bytes; the operating system set to the current system (\x00= Windows,\x03= Unix, etc.)
encodingOne of theZLIB_ENCODING_*constants.
optionsAn associative array which may contain the following elements:
The compression level in range -1..9; defaults to -1.
The compression memory level in range 1..9; defaults to 8.
The zlib window size (logarithmic) in range8..15; defaults to15. zlib changes a window size of8to9, and as of zlib 1.2.8 fails with a warning, if a window size of8is requested forZLIB_ENCODING_RAWorZLIB_ENCODING_GZIP.
One ofZLIB_FILTERED,ZLIB_HUFFMAN_ONLY,ZLIB_RLE,ZLIB_FIXEDorZLIB_DEFAULT_STRATEGY(the default).
Astringor anarrayofstringsof the preset dictionary (default: no preset dictionary).
Returns a deflate context resource (zlib.deflate) on success, ofalseen caso de error.
If an invalid option is passed tooptionsor the context couldn't be created, an error of levelE_WARNINGis generated.
| Versión | Descripción |
|---|---|
| 8.0.0 | On success, this function returns aDeflateContextinstance now; previously, aresourcewas returned. |
(PHP 4, PHP 5, PHP 7, PHP 8)
gzclose—Cierra el apuntador de un archivo gz abierto
$stream):boolCierra el apuntador del archivo gz dado.
streamEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
Devuelvetrueen caso de éxito ofalseen caso de error.
Ejemplo #1 Ejemplo degzclose()
<?php
$gz=gzopen('somefile.gz','w9');
gzputs($gz,'I was added to somefile.gz');
gzclose($gz);
?>(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
gzcompress—Comprime una cadena
$data,int$level= -1,int$encoding=ZLIB_ENCODING_DEFLATE):string|falseEsta función comprime la cadena dada usando el formato de datosZLIB.
Para detalles sobre el algoritmo de compresión ZLIB, ver el documento "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).
Nota:
Estonoes lo mismo que la compresión que gzip, la cuál incluye algunos encabezados de datos. Vergzencode()para la compresión gzip.
dataLos datos a comprimir.
levelEl nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión.
Si se utiliza -1, se usará la compresión por defecto de la librería zlib la cual es 6.
encodingUna de las constentesZLIB_ENCODING_*.
La cadena comprimida ofalsesi ocurre un error.
Ejemplo #1 Ejemplo degzcompress()
<?php
$compressed=gzcompress('Compress me',9);
echo$compressed;
?>(PHP 5 >= 5.4.0, PHP 7, PHP 8)
gzdecode—Decodifica una cadena comprimida con gzip
$data,int$max_length= 0):string|falseEstá función retorna una versión decodificada de la entradadata.
dataLos datos para decodificar, codificados congzencode().
max_lengthLa longitud máxima de datos que decodificar.
La cadena decodificada ofalsesi ocurre un error.
(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
gzdeflate—Comprime una cadena
$data,int$level= -1,int$encoding=ZLIB_ENCODING_RAW):string|falseEsta función comprime la cadena dada utilizando el formato de datosDEFLATE.
Para más detalles sobre el algoritmo de compresión DEFLATE ver el documento "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).
dataLos datos a comprimir.
levelEl nivel de compresión. Se puede dar desde 0 para ninguna compresión hasta 9 para máxima compresión. Si no se especifica, se utilizará el nivel de compresión por defecto de la librería zlib.
encodingUna de las constantesZLIB_ENCODING_*.
La cadena comprimida ofalsesi ocurre un error.
Ejemplo #1 Ejemplo degzdeflate()
<?php
$compressed=gzdeflate('Compress me',9);
echo$compressed;
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
gzencode—Crea una cadena comprimida con gzip
$data,int$level= -1,int$encoding_mode= FORCE_GZIP):stringEsta función retorna una versión comprimida de ladatade entrada, compatible con la salida del programagzip.
Para más información sobre el formato de archivo GZIP, ver el documento:» GZIP file format specification version 4.3(RFC 1952).
dataLos datos a codificar.
levelEl nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión. Si no se incluye, se utilizará el nivel de compresión por defecto de la librería zlib.
encoding_modeEl modo de codificación. Puede serFORCE_GZIP(por defecto) oFORCE_DEFLATE.
Antes de PHP 5.4.0, utilizarFORCE_DEFLATEresultaba en un string comprimido zlib estándar (incluyendo encabezados de la librería) después del encabezado de archivo gzip pero sin el cierre de la suma de control crc32.
En PHP 5.4.0 y posterior,FORCE_DEFLATEgenera una salida que cumple el RFC 1950, consistente en un encabezado zlib, los datos comprimidos y una suma de control Adler.
La cadena codificada ofalsesi ocurre un error.
| Versión | Descripción |
|---|---|
| 5.4.0 | FORCE_DEFLATEahora genera una salida que cumple el RFC 1950. |
Los datos resultantes contienen los encabezados y estructura de datos apropiados para construir un archivo .gz estándar, por ejemplo:
Ejemplo #1 Creando un archivo gzip
<?php
$data=implode("",file("bigfile.txt"));
$gzdata=gzencode($data,9);
$fp=fopen("bigfile.txt.gz","w");
fwrite($fp,$gzdata);
fclose($fp);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzeof—Prueba de apuntador paraEOFde archivo gz
$stream):boolPrueba el apuntador de archivo GZ dado en busca delEOF(fin de archivo).
streamEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
Retornatruesi el apuntador GZ está alEOFdel archivo o si ocurrió un error; de lo contrario retornafalse.
Ejemplo #1 Ejemplo degzeof()
<?php
$gz=gzopen('somefile.gz','r');
while (!gzeof($gz)) {
echogzgetc($gz);
}
gzclose($gz);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzfile—Lee un archivo gz completo en una matriz
$filename,int$use_include_path= 0):array|falseEstá función es identica areadgzfile(), excepto que retorna el archivo en una matriz.
filenameEl nombre del archivo.
use_include_pathSe puede asignar este parámetro opcional en1, si se desea buscar también el archivo en la rutainclude_path.
Una matriz que contiene el archivo, una línea por celda, incluidas líneas vacías, y con líneas nuevas aún unidas, ofalseen caso de error.
Ejemplo #1 Ejemplo degzfile()
<?php
$lines=gzfile('somefile.gz');
foreach ($linesas$line) {
echo$line;
}
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzgetc—Obtiene el caracter donde está el apuntador al archivo gz
$stream):string|falseRetorna una cadena que contiene un solo caracter (sin comprimir) leído del apuntador al archivo gz dado.
streamEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
El caracter sin comprimir ofalseen caso deEOF(a diferencia degzeof()).
Ejemplo #1 Ejemplo degzgetc()
<?php
$gz=gzopen('somefile.gz','r');
while (!gzeof($gz)) {
echogzgetc($gz);
}
gzclose($gz);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzgets—Obtiene la línea del apuntador al archivo
$zp,int$length= ?):stringObtiene una cadena (sin comprimir) de hasta un largo de - 1 bytes leídos desde el apuntador al archivo dado. La lectura termina cuando el largo de - 1 bytes ha sido leído, en un salto de línea o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
lengthLa longitud de los datos a obtener.
La cadena sin comprimir ofalseen caso de error.
Ejemplo #1 Ejemplo degzgets()
<?php
$handle=gzopen('somefile.gz','r');
while (!gzeof($handle)) {
$buffer=gzgets($handle,4096);
echo$buffer;
}
gzlose($handle);;
?>(PHP 4, PHP 5, PHP 7)
gzgetss—Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
Esta función ha sido declaradaOBSOLETAa partir de PHP 7.3.0. Su uso está totalmente desaconsejado.
$zp,int$length,string$allowable_tags= ?):stringFunción identica agzgets(), excepto quegzgetss()intenta retirar cualquier etiqueta HTML y PHP del texto que esta leyendo.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
lengthLa longitud de los datos a obtener.
allowable_tagsSe puede usar éste parámetro opcional para especificar cuales etiquetas no se deben retirar.
La cadena descomprimida y sin etiquetas ofalseen caso de error.
Ejemplo #1 Ejemplo degzgetss()
<?php
$handle=gzopen('somefile.gz','r');
while (!gzeof($handle)) {
$buffer=gzgetss($handle,4096);
echo$buffer;
}
gzlose($handle);
?>(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)
gzinflate—Descomprime una cadena comprimida
$data,int$max_length= 0):string|falseEsta función descomprime una cadena comprimida.
dataLos datos comprimidos congzdeflate().
max_lengthLa longitud máxima de datos a decodificar.
Los datos originales descomprimidos ofalseen caso de error.
La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de ladatade entrada o mayores que el parámetro opcionalmax_length.
Ejemplo #1 Ejemplo degzinflate()
<?php
$compressed=gzdeflate('Compress me',9);
$uncompressed=gzinflate($compressed);
echo$uncompressed;
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzopen—Abre un archivo gz
$filename,string$mode,int$use_include_path= 0):resource|falseAbre un archivo gzip (.gz) para lectura o escritura.
gzopen()se puede usar para leer un archivo el cual no esté en formato gzip; en este casogzread()leerá directamente el archivo sin descomprimirlo.
filenameEl nombre del archivo.
modeComo enfopen()(rbowb) pero también puede incluir un nivel de compresión (wb9) u una estrategia:fpara datos filtrados como enwb6f,hparacompresión Huffman solamentecomo enwb1h. (Ver la descripción dedeflateInit2enzlib.hpara más información sobre el parámetro de estrategia.)
use_include_pathSe puede configurar este parámetro opcional en1, si se desea buscar también el archivo en la rutainclude_path.
Retorna un apuntador hacia el archivo abierto, después de eso, cualquier cosa que se lea desde este descriptor de archivo sera descomprimido de forma transparente y lo que se escriba será comprimido.
Si falla la apertura, la función retornafalse.
Ejemplo #1 Ejemplo degzopen()
<?php
$fp=gzopen("/tmp/file.gz","r");
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzpassthru—Muestra todos los datos restantes a partir del apuntador al achivo gz
$zp):intLee hasta elEOFdesde la posición en el apuntador al archivo gz y escribe los resultados (sin comprimir) en la salida estándar.
Nota:
Se puede necesitar llamar a la funcióngzrewind()para restablecer el apuntador al inicio del archivo, si ya se han escrito datos en él.
Si sólo se desea volcar el contenido de un archivo en el buffer de salida, sin modificarlo primero o buscando una posición particular, se puede usar la funciónreadgzfile(), la cual ahorra el llamado a la funcióngzopen().
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
El número de carácteres sin comprimir leídos degzy pasados a través de la entrada, ofalseen caso de error.
Ejemplo #1 Ejemplo degzpassthru()
<?php
$fp=gzopen('file.gz','r');
gzpassthru($fp);
gzclose($fp);
?>Esta función es un alias de:gzwrite().
(PHP 4, PHP 5, PHP 7, PHP 8)
gzread—Lectura de archivo gz segura a nivel binario
$zp,int$length):stringgzread()lee los bytes hasta el parámetrolengthdesde el apuntador al archivo gz dado. La lectura se detiene cuando los bytes del parámetrolength(sin comprimir) sean leídos o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
lengthEl número de bytes a leer.
Los datos que han sido leídos.
Ejemplo #1 Ejemplo degzread()
<?php
// pasar los contenidos de un archivo gz a una cadena
$filename="/usr/local/something.txt.gz";
$zd=gzopen($filename,"r");
$contents=gzread($zd,10000);
gzclose($zd);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzrewind—Reinicia la posición del apuntador a un archivo gz
$stream):boolColoca el indicador de posición del apuntador al archivo gz dado al comienzo del flujo del archivo.
streamEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
Devuelvetrueen caso de éxito ofalseen caso de error.
(PHP 4, PHP 5, PHP 7, PHP 8)
gzseek—Ubica el apuntador a un archivo gz
$zp,int$offset,int$whence= SEEK_SET):intEstablece el indicador de posición para el apuntador al archivo dado en el desplazamiento de bytes fijado en el flujo del archivo. Es equivalente a llamar (en C) agzseek(zp, offset, SEEK_SET).
Si el archivo está abierto para lectura, ésta función es emulada pero puede ser extremadamente lenta. Si el archivo está abierto para escritura, sólo está soportada la búsqueda hacia adelante; entoncesgzseek()comprime una secuencia de ceros hasta la nueva posición de inicio.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
offsetEl desplazamiento buscado.
whenceLos valores dewhenceson:
SEEK_SET- Establece la posición igual aloffsetde bytes.SEEK_CUR- Establece la posición en la posición actual más eloffset.Siwhenceno se especifica, se asume que esSEEK_SET.
En caso de éxito, retorna 0; en caso contrario, devuelve -1. Notese que buscar pasado el EOF no es considerado un error.
Ejemplo #1 Ejamplo degzseek()
<?php
$gz=gzopen('somefile.gz','r');
gzseek($gz,2);
echogzgetc($gz);
gzclose($gz);
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gztell—Indica la posición de lectura/escritura del apuntador al archivo gz
$zp):intObtiene la posición del apuntador al archivo dado; por ejemplo, su desplazamiento en el flujo del archivo sin comprimir.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
La posición del apuntador al archivo ofalsesi ocurre un error.
(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
gzuncompress—Descomprime una cadena comprimida
$data,int$length= 0):stringEstá función descomprime una cadena comprimida
dataLos datos comprimidos congzcompress().
lengthLa longitud máxima de datos a decodificar.
Los datos originales sin comprimir ofalseen caso de error.
La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de la entrada comprimidadatao mayores que el parámetro opcionallength.
Ejemplo #1 Ejemplo degzuncompress()
<?php
$compressed=gzcompress('Compress me',9);
$uncompressed=gzuncompress($compressed);
echo$uncompressed;
?>(PHP 4, PHP 5, PHP 7, PHP 8)
gzwrite—Escritura en un archivo gz, segura a nivel binario
$zp,string$string,int$length= ?):intgzwrite()escribe el contenido decadenaal archivo gz dado.
zpEl apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().
stringLa cadena a escribir.
lengthEl número de bytes sin comprimir a escribir. Si se suministra, la escritura se detendrá después de que se hayan escrito los bytes (sin comprimir) del parámetrolengtho de que sea alcanzado el fin de lastring, lo que ocurra primero.
Nota:
Nótese que si se da el argumento
length, entonces la opción de configuraciónmagic_quotes_runtimeserá ignorada y ningún slash será retirado de lastring.
Retorna el número de bytes (sin comprimir) escritos en el flujo del archivo gz dado.
Ejemplo #1 Ejemplo degzwrite()
<?php
$string='Some information to compress';
$gz=gzopen('somefile.gz','w9');
gzwrite($gz,$string);
gzclose($gz);
?>(PHP 7, PHP 8)
inflate_add—Incrementally inflate encoded data
Incrementally inflates encoded data in the specifiedcontext.
Limitation: header information from GZIP compressed data are not made available.
contextA context created withinflate_init().
dataA chunk of compressed data.
flush_modeOne ofZLIB_BLOCK,ZLIB_NO_FLUSH,ZLIB_PARTIAL_FLUSH,ZLIB_SYNC_FLUSH(default),ZLIB_FULL_FLUSH,ZLIB_FINISH. Normally you will want to setZLIB_NO_FLUSHto maximize compression, andZLIB_FINISHto terminate with the last chunk of data. See the» zlib manualfor a detailed description of these constants.
Returns a chunk of uncompressed data, ofalseen caso de error.
If invalid parameters are given, inflating the data requires a preset dictionary, but none is specified, the compressed stream is corrupt or has an invalid checksum, an error of levelE_WARNINGis generated.
| Versión | Descripción |
|---|---|
| 8.0.0 | contextexpects anInflateContextinstance now; previously, aresourcewas expected. |
(PHP 7 >= 7.2.0, PHP 8)
inflate_get_read_len—Get number of bytes read so far
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
contextReturns number of bytes read so far ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 8.0.0 | contextexpects anInflateContextinstance now; previously, aresourcewas expected. |
(PHP 7 >= 7.2.0, PHP 8)
inflate_get_status—Get decompression status
Usually returns eitherZLIB_OKorZLIB_STREAM_END.
contextReturns decompression status ofalseen caso de error.
| Versión | Descripción |
|---|---|
| 8.0.0 | contextexpects anInflateContextinstance now; previously, aresourcewas expected. |
(PHP 7, PHP 8)
inflate_init—Initialize an incremental inflate context
Initialize an incremental inflate context with the specifiedencoding.
encodingOne of theZLIB_ENCODING_*constants.
optionsAn associative array which may contain the following elements:
The compression level in range -1..9; defaults to -1.
The compression memory level in range 1..9; defaults to 8.
The zlib window size (logarithmic) in range 8..15; defaults to 15.
One ofZLIB_FILTERED,ZLIB_HUFFMAN_ONLY,ZLIB_RLE,ZLIB_FIXEDorZLIB_DEFAULT_STRATEGY(the default).
Astringor anarrayofstringsof the preset dictionary (default: no preset dictionary).
Returns an inflate context resource (zlib.inflate) on success, ofalseen caso de error.
If an invalid encoding or option is passed tooptions, or the context couldn't be created, an error of levelE_WARNINGis generated.
| Versión | Descripción |
|---|---|
| 8.0.0 | On success, this function returns anInflateContextinstance now; previously, aresourcewas returned. |
(PHP 4, PHP 5, PHP 7, PHP 8)
readgzfile—Muestra un archivo gz
$filename,int$use_include_path= 0):intLee un archivo, lo descomprime y lo escribe en la salida estándar.
La funciónreadgzfile()puede ser usada para leer un archivo que no esté en formato gzip; en éste casoreadgzfile()leerá directamente el archivo sin hacer la descompresión.
filenameEl nombre del archivo. Este archivo será abierto del sistema de archivos y sus contenidos escritos en la salida estándar.
use_include_pathSe puede especificar éste parámetro opcional en1, si también se desea buscar el archivo en la rutainclude_path.
Devuelve el número de bytes (sin comprimir) leídos del archivo en caso de éxito, ofalseen caso de error
En caso de fallo, se emite unE_WARNING.
(PHP 5 >= 5.4.0, PHP 7, PHP 8)
zlib_decode—Descomprime datos codificados en craw/gzip/zlib
$data,string$max_decoded_len= ?):stringDescomprime datos codificados en raw/gzip/zlib.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
datamax_decoded_lenDevuelve los datos no comprimidos, ofalseen caso de error.
(PHP 5 >= 5.4.0, PHP 7, PHP 8)
zlib_encode—Comprime datos con la codificación especificada
$data,int$encoding,int$level= -1):stringComprime datos con la codificación especificada.
Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.
dataLos datos a comprimir.
encodingEl algoritmo de compresión. O bienZLIB_ENCODING_RAW,ZLIB_ENCODING_DEFLATEoZLIB_ENCODING_GZIP.
levelEjemplo #1 Ejemplo dezlib_encode()
<?php
$str='hello world';
$enc=zlib_encode($str,ZLIB_ENCODING_DEFLATE);
echobin2hex($enc);
?>El resultado del ejemplo sería:
789ccb48cdc9c95728cf2fca4901001a0b045d
(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)
zlib_get_coding_type—Retorna el tipo de codificación utilizada para hacer la compresión
Retorna el tipo de codificación utilizada para hacer la compresión.
Los posibles valores de retorno songzip,deflateofalse.
(PHP 8)
Una clase completamente opaca que reemplaza los recursoszlib.deflatea partir de PHP 8.0.0.
(PHP 8)
A fully opaque class which replaceszlib.inflateresources as of PHP 8.0.0.
Motor para cifrar mensajes (hash). Permite la transformación directa o incremental de mensajes de longitud arbitraria usando una variedad de algoritmos hash.
No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.
A partir de PHP 5.1.2, la extensión Hash está incluida y copilada en PHP de forma predeterminada.
Se puede deshabilitar explícitamente utilizando la opción --disable-hash de la configuración. En versiones anteriores de PHP se puede incorporar la extensión Hash instalando el» módulo PECL.
Esta extensión no tiene directivas de configuración definidas enphp.ini.
Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.
HASH_HMAC(integer)(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_algos—Devuelve una lista con los algoritmos de cifrado soportados
Devuelve un array numérico que contiene una lista con los tipos de algoritmos de cifrado soportados.
| Versión | Descripción |
|---|---|
| 5.6.0 | Se añadió soprte para gost-crypto. Este implementa la función de hash GOST empleando las tablas CryptoPro S-box como está especificado en la» RFC 4357, sección 11.2. |
| 5.4.0 | Se añade soporte para joaat, fnv132 y para fnv164. Soporte para Salsa10 y Salsa20 fué eliminado. |
| 5.3.0 | Se añade soporte para md2, ripemd256, ripemd320, salsa10, salsa20, snefru256 y para sha224 |
Ejemplo #1hash_algos()ejemplo
A partir de PHP 5.6.0,hash_algos()devuelve la siguiente lista de nombres de algoritmos.
<?php
print_r(hash_algos());
?>El resultado del ejemplo sería algo similar a:
Array
(
[0] => md2
[1] => md4
[2] => md5
[3] => sha1
[4] => sha224
[5] => sha256
[6] => sha384
[7] => sha512
[8] => ripemd128
[9] => ripemd160
[10] => ripemd256
[11] => ripemd320
[12] => whirlpool
[13] => tiger128,3
[14] => tiger160,3
[15] => tiger192,3
[16] => tiger128,4
[17] => tiger160,4
[18] => tiger192,4
[19] => snefru
[20] => snefru256
[21] => gost
[22] => gost-crypto
[23] => adler32
[24] => crc32
[25] => crc32b
[26] => fnv132
[27] => fnv1a32
[28] => fnv164
[29] => fnv1a64
[30] => joaat
[31] => haval128,3
[32] => haval160,3
[33] => haval192,3
[34] => haval224,3
[35] => haval256,3
[36] => haval128,4
[37] => haval160,4
[38] => haval192,4
[39] => haval224,4
[40] => haval256,4
[41] => haval128,5
[42] => haval160,5
[43] => haval192,5
[44] => haval224,5
[45] => haval256,5
)
(PHP 5 >= 5.3.0, PHP 7, PHP 8)
hash_copy—Copia un recurso de contexto de cifrado
$context):resourcecontextContexto para cifrado que se obtiene mediantehash_init().
Devuelve una copia del recurso de un contexto de cifrado.
Ejemplo #1Ejemplo de hash_copy()
<?php
$context=hash_init("md5");
hash_update($context,"data");
/* copy context to be able to continue using it */
$copy_context=hash_copy($context);
echohash_final($context),"\n";
hash_update($copy_context,"data");
echohash_final($copy_context),"\n";
?>El resultado del ejemplo sería:
8d777f385d3dfec8815d20f7496026dc 511ae0b1c13f95e5f08f1a0dd3da3d93
(PHP 5 >= 5.6.0, PHP 7, PHP 8)
hash_equals—Comparación de strings segura contra ataques de temporización
$known_string,string$user_string):boolCompara dos strings empleando el mismo tiempo, sin importar si son iguales o no.
Esta función debería utilizarse para mitigar los ataques de temporización, por ejemplo, al probar hash de contraseñas decrypt().
known_stringElstringde longitud conocida con el que comparar
user_stringEl string proporcionado por el usuario
Devuelvetruecuando los dos strings son iguales, ofalsesi no.
Emite un mensaje de nivelE_WARNINGcuando ninguno de los parámetros proporcionados es un string.
Ejemplo #1 Ejemplohash_equals()
<?php
$esperado=crypt('12345','$2a$07$usesomesillystringforsalt$');
$correcto=crypt('12345','$2a$07$usesomesillystringforsalt$');
$incorrecto=crypt('apple','$2a$07$usesomesillystringforsalt$');
var_dump(hash_equals($esperado,$correcto));
var_dump(hash_equals($esperado,$incorrecto));
?>El resultado del ejemplo sería:
bool(true) bool(false)
Nota:
Ambos argumentos deber tener la misma longitud para que se puedan comparar. Cuando se proporcionan argumentos con diferente longitud, se devuelve
falseinmediatamente, pudiéndose filtrar la longitud del string conocido en caso de un ataque de temporización.
Nota:
Es importante proveer el string proporcionado por el usuario como segundo parámetro, en vez de como el primero.
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_file—Generar un valor hash usando el contenido de un fichero dado
$algo,string$filename,bool$raw_output=false):stringalgoNombre del algoritmo hash seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Para una lista de los algoritmos soportados véasehash_algos().
filenameURL que describe la ubicación del fichero que se va a procesar; Soporta envoltorios abiertos (fopen).
raw_outputCuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.
Devuelve un string que contiene el resumen del mensaje calculado como hexágonos en minúsculas a menos que el parámetroraw_outputsea establecido en cuyo caso se devuelve la representación binaria en bruto del resumen del mensaje.
Ejemplo #1 Usandohash_file()
<?php
/* Creamos un fichero para calcular su resultante valor cifrado */
file_put_contents('example.txt','The quick brown fox jumped over the lazy dog.');
echohash_file('md5','example.txt');
?>El resultado del ejemplo sería:
5c6ffbdd40d9556b73a21e63c3e0e904
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_final—Finaliza un contexto incremental y devuelve el resultado cifrado
$context,bool$raw_output= false):stringcontextContexto para cifrado que se obtiene mediantehash_init().
raw_outputCuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.
Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato.
Ejemplo #1 Ejemplo dehash_final()
<?php
$ctx=hash_init('sha1');
hash_update($ctx,'The quick brown fox jumped over the lazy dog.');
echohash_final($ctx);
?>El resultado del ejemplo sería:
c0854fb9fb03c41cce3802cb0d220529e6eef94e
(PHP 7 >= 7.1.2, PHP 8)
hash_hkdf—Generate a HKDF key derivation of a supplied key input
$algo,$key,$length= 0,$info= "",$salt= ""algoName of selected hashing algorithm (i.e. "sha256", "sha512", "haval160,4", etc..) Seehash_algos()for a list of supported algorithms.
Nota:
Non-cryptographic hash functions are not allowed.
keyInput keying material (raw binary). Cannot be empty.
lengthDesired output length in bytes. Cannot be greater than 255 times the chosen hash function size.
Iflengthis0, the output length will default to the chosen hash function size.
infoApplication/context-specific info string.
saltSalt to use during derivation.
While optional, adding random salt significantly improves the strength of HKDF.
Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM).
Throws aValueErrorexception ifkeyis empty,algois unknown/non-cryptographic,lengthis less than0or too large (greater than 255 times the size of the hash function).
| Versión | Descripción |
|---|---|
| 8.0.0 | Now throws aValueErrorexception on error. Previously,falsewas returned and anE_WARNINGmessage was emitted. |
Ejemplo #1hash_hkdf()example
<?php
// Generate a random key, and salt to strengthen it during derivation.
$inputKey=random_bytes(32);
$salt=random_bytes(16);
// Derive a pair of separate keys, using the same input created above.
$encryptionKey=hash_hkdf('sha256',$inputKey,32,'aes-256-encryption',$salt);
$authenticationKey=hash_hkdf('sha256',$inputKey,32,'sha-256-authentication',$salt);
var_dump($encryptionKey!==$authenticationKey);// bool(true)
?>The above example produces a pair of separate keys, suitable for creation of an encrypt-then-HMAC construct, using AES-256 and SHA-256 for encryption and authentication respectively.
(PHP 7 >= 7.2.0, PHP 8)
hash_hmac_algos—Return a list of registered hashing algorithms suitable for hash_hmac
Esta función no tiene parámetros.
Returns a numerically indexed array containing the list of supported hashing algorithms suitable forhash_hmac().
Ejemplo #1hash_hmac_algos()example
<?php
print_r(hash_hmac_algos());El resultado del ejemplo sería algo similar a:
Array
(
[0] => md2
[1] => md4
[2] => md5
[3] => sha1
[4] => sha224
[5] => sha256
[6] => sha384
[7] => sha512/224
[8] => sha512/256
[9] => sha512
[10] => sha3-224
[11] => sha3-256
[12] => sha3-384
[13] => sha3-512
[14] => ripemd128
[15] => ripemd160
[16] => ripemd256
[17] => ripemd320
[18] => whirlpool
[19] => tiger128,3
[20] => tiger160,3
[21] => tiger192,3
[22] => tiger128,4
[23] => tiger160,4
[24] => tiger192,4
[25] => snefru
[26] => snefru256
[27] => gost
[28] => gost-crypto
[29] => haval128,3
[30] => haval160,3
[31] => haval192,3
[32] => haval224,3
[33] => haval256,3
[34] => haval128,4
[35] => haval160,4
[36] => haval192,4
[37] => haval224,4
[38] => haval256,4
[39] => haval128,5
[40] => haval160,5
[41] => haval192,5
[42] => haval224,5
[43] => haval256,5
)
Nota:
Before PHP 7.2.0 the only means to get a list of supported hash algorithms has been to callhash_algos()which also returns hash algorithms that are not suitable forhash_hmac().
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_hmac_file—Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado
$algo,$filename,$key,$raw_output= falsealgoNombre del algoritmo para cifrar seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Verhash_algos()para saber la lista de algoritmos soportados.
filenameURL que describe la localización del fichero cuyo contenido vamos a cifrar; Soporta fopen wrappers.
keyClave secreta compartida que se usará para generar el mensaje cifrado de la variante HMAC.
raw_outputCuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.
Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato.
Ejemplo #1Ejemplo de hash_hmac_file()
<?php
/* Creamos un fichero para calcular su resultante valor cifrado */
file_put_contents('example.txt','The quick brown fox jumped over the lazy dog.');
echohash_hmac_file('md5','example.txt','secret');
?>El resultado del ejemplo sería:
7eb2b5c37443418fc77c136dd20e859c
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_hmac—Genera un valor cifrado mediante una clave especificada usando el método HMAC
$algo,$data,$key,$raw_output= falsealgoNombre del algoritmo para cifrar seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Verhash_algos()para saber la lista de algoritmos soportados.
dataMensaje para cifrar.
keyClave secreta compartida que se usará para generar el mensaje cifrado de la variante HMAC.
raw_outputCuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.
Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato. Devuelvefalsecuandoalgoes desconocido.
Ejemplo #1hash_hmac()example
<?php
echohash_hmac('ripemd160','The quick brown fox jumped over the lazy dog.','secret');
?>El resultado del ejemplo sería:
b8e7ae12510bdfb1812e463a7f086122cf37e4f7
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_init—Iniciar un contexto de hashing incremental
$algo,int$options= 0,string$key=null):HashContextalgoNombre del algoritmo hash seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Para una lista de los algoritmos admitidos véasehash_algos().
optionsConfiguración opcional para la generación del cifrado, normalmente soporta solo una opción:HASH_HMAC, en el caso de utilizar esta opción tambiéndeberemosespecificar el parámetrokey.
keyCuando se especifiqueHASH_HMACenoptions, se debe suministrar una clave secreta compartida en este parámetro para ser utilizada en el método de cifrado HMAC.
Devuelve un recurso de contexto para cifrado, el cual será incrementado conhash_update(),hash_update_stream(),hash_update_file(), yhash_final().
| Versión | Descripción |
|---|---|
| 7.2.0 | Uso de funciones de hash no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) conHASH_HMACha sido deshabilitado. |
| 7.2.0 | DevuelveHashContexten lugar de recurso. |
Ejemplo #1 Ejemplo de hashing incremental
<?php
$ctx=hash_init('md5');
hash_update($ctx,'The quick brown fox ');
hash_update($ctx,'jumped over the lazy dog.');
echohash_final($ctx);
?>El resultado del ejemplo sería:
5c6ffbdd40d9556b73a21e63c3e0e904
(PHP 5 >= 5.5.0, PHP 7, PHP 8)
hash_pbkdf2—Genera una derivación de clave PBKDF2 de una contraseña proporcionada
$algo,$password,$salt,$iterations,$length= 0,$raw_output= falsealgoEl nombre del algoritmo hash seleccionado (esto es,"md5","sha256","haval160,4", etc.). Véasehash_algos()para una lista de los algoritmos admitidos.
passwordLa contraseña a usar para la derivación.
saltLa sal a usar para la derivación. Este valor debería ser generado aleatoriamente.
iterationsEl número de iteraciones internas para realizar la derivación.
lengthLa longitud del string de salida. Siraw_outputestrue, se corresponde con la longitud en bytes de la clave derivada; siraw_outputesfalse, se corresponde con dos veces la longitud en bytes de la clave derivada (ya que cada byte de la clave es devuelto como dos dígitos hexadecimales).
Si se pasa0, se usará la salida completa del algoritmo proporcionado.
raw_outputCuando se establece atrue, genera datos binarios puros.falsegenera dígitos hexadecimales en minúsculas.
Devuelve un string que contiene la clave derivada como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido atrue, en cuyo caso devuelve la represetación binaria pura de la clave derivada.
Se emitirá unE_WARNINGsi el algoritmo es desconocido, el parámetroiterationses menor o igual a0, el parámetrolengthes menor que0o el parámetrosaltes demasiado grande (mayor queINT_MAX- 4).
Ejemplo #1 Ejemplo de uso básico dehash_pbkdf2()
<?php
$contraseña="password";
$iteraciones=1000;
// Generar una IV aleatoria usando mcrypt_create_iv(),
// openssl_random_pseudo_bytes() u otra fuente disponible de aleatoriedad
$sal=mcrypt_create_iv(16,MCRYPT_DEV_URANDOM);
$hash=hash_pbkdf2("sha256",$contraseña,$sal,$iteraciones,20);
echo$hash;
?>El resultado del ejemplo sería algo similar a:
120fb6cffcf8b32c43e7
El método PBKDF2 se puede usar para el almacenamiento de contraseñas de hash. Sin embargo, se debería observar quepassword_hash()ocrypt()conCRYPT_BLOWFISHson más adecuados para el almacenamiento de contraseñas.
(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)
hash_update_file—Inyecta datos en un contexto de cifrado activo desde un fichero
$hcontext,string$filename,resource$scontext=null):boolhcontextUn contexto de cifrado devuelto porhash_init().
filenameURL que describe la ubicación del fichero a cifrar; admite envolturas fopen.
scontextUn contexto de flujo, como el devuelto porstream_context_create().
Devuelvetrueen caso de éxito ofalseen caso de error.